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

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

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

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

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

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

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

نمونه پایه‌بار

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

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