از کارت شناسایی موقت استفاده کنید، از کارت شناسایی موقت استفاده کنید، از کارت شناسایی موقت استفاده کنید

نام‌های منابع موقت

BatchJobService از نام‌های منبع موقت پشتیبانی می‌کند که می‌توانند در عملیات‌های بعدی در همان کار دسته‌ای - از جمله در چندین درخواست متوالی AddBatchJobOperations که با sequence_token آپلود شده‌اند - به آنها ارجاع داده شوند. این به شما امکان می‌دهد قبل از اختصاص شناسه‌های سمت سرور، یک کمپین و گروه‌های تبلیغاتی، تبلیغات و معیارهای وابسته به آن را در یک کار دسته‌ای واحد ایجاد کنید. در قوانین کلی و مثال زیر، یک درخواست واحد به کل یک BatchJob در تمام آپلودهای AddBatchJobOperations آن اشاره دارد.

برای ارجاع به یک منبع تازه ایجاد شده در همان درخواست تغییر یا کار دسته‌ای، یک شناسه عدد صحیح منفی (مانند -1 یا -2 ، به استثنای 0 ) در فیلد resource_name منبع جدید مشخص کنید. برای مثال، هنگام ایجاد یک کمپین در یک درخواست دسته‌ای، نام منبع آن را روی customers/CUSTOMER_ID/campaigns/-1 تنظیم کنید. هنگام ایجاد یک گروه تبلیغاتی در یک عملیات بعدی در همان درخواست، customers/CUSTOMER_ID/campaigns/-1 را به عنوان کمپین والد ارجاع دهید. API به طور خودکار -1 را با شناسه واقعی کمپین ایجاد شده هنگام ایجاد جایگزین می‌کند.

محدودیت‌های استفاده

هنگام استفاده از نام‌های موقت منابع، قوانین زیر را در نظر داشته باشید:

• اهمیت ترتیب: شما فقط می‌توانید پس از تعریف یک منبع موقت، به آن ارجاع دهید. در فهرست عملیات، عملیات وابسته (مانند ایجاد یک گروه تبلیغاتی) باید پس از عملیاتی که منبع والد خود را ایجاد می‌کند (مانند ایجاد یک کمپین) ظاهر شود.
• دامنه تک درخواستی یا دسته‌ای: نام‌های منابع موقت در بین کارهای جداگانه یا درخواست‌های تغییر یافته باقی نمی‌مانند. برای ارجاع به منبعی که در یک کار قبلی یا درخواست تغییر یافته ایجاد شده است، از نام منبع واقعی تولید شده توسط سیستم استفاده کنید.
• منحصر به فرد بودن سراسری: در یک درخواست تغییر یا کار واحد، هر نام منبع موقت باید از یک عدد صحیح منفی منحصر به فرد در تمام انواع منابع استفاده کند. به عنوان مثال، شما نمی‌توانید در یک درخواست واحد -1 را به یک کمپین و یک گروه تبلیغاتی اختصاص دهید. استفاده مجدد از یک شناسه موقت در یک درخواست یا کار دسته‌ای واحد، خطای NewResourceCreationError.DUPLICATE_TEMP_IDS را برمی‌گرداند.

مثال بار مفید

فرض کنید می‌خواهید یک کمپین، یک گروه تبلیغاتی و یک تبلیغ را در یک درخواست API یا کار دسته‌ای اضافه کنید. می‌توانید آرایه mutateOperations را در یک درخواست GoogleAdsService.Mutate یا BatchJobService.AddBatchJobOperations همانطور که در مثال REST JSON زیر نشان داده شده است، ساختار دهید (سایر فیلدهای منبع مورد نیاز برای اختصار حذف شده‌اند):

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

این مثال جزئیات کلیدی زیر را نشان می‌دهد:

• گروه تبلیغاتی از یک شناسه موقت جدید ( -2 ) استفاده می‌کند زیرا -1 قبلاً به کمپین اختصاص داده شده است.
• این گروه تبلیغاتی برای پیوند دادن خود به کمپین ایجاد شده در عملیات قبلی، به customers/CUSTOMER_ID/campaigns/-1 ارجاع می‌دهد.
• تابع adGroupAdOperation به customers/CUSTOMER_ID/adGroups/-2 ارجاع می‌دهد و resourceName حذف می‌کند، زیرا هیچ عملیات بعدی در درخواست به تبلیغ جدید ارجاع نمی‌دهد.

مدیریت خطا در کارهای دسته‌ای

از آنجا که عملیات استاندارد در یک کار دسته‌ای با فعال بودن خطای جزئی اجرا می‌شوند (به جز در زیردسته‌های اتمی )، اگر یک منبع والد با شناسه موقت اعتبارسنجی نشود، هر عملیات فرزند وابسته که به آن شناسه موقت ارجاع می‌دهد با خطای NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS مواجه می‌شود. استفاده مجدد از همان شناسه منفی در چندین عملیات create در همان کار دسته‌ای، NewResourceCreationError.DUPLICATE_TEMP_IDS را برمی‌گرداند. شناسه‌های موقت فقط هنگام ایجاد منابع ( create ) یا ارجاع به منابع والد تازه ایجاد شده معتبر هستند. به عنوان مثال، ارسال یک شناسه موقت منفی در AdGroupCriterionOperation.remove هنگام فراخوانی AddBatchJobOperations RequestError.RESOURCE_NAME_MALFORMED را برمی‌گرداند.