استفاده از شناسه‌های موقت

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

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 را برمی‌گرداند.