روال‌های مطلوب و محدودیت‌ها

هنگام استفاده از BatchJobService، این دستورالعمل‌ها را درنظر بگیرید.

بهبود توان عملیاتی

  • تعداد کمی کار بزرگ‌تر به تعداد زیادی کار کوچک‌تر ترجیح داده می‌شود.

  • عملیات بارگذاری‌شده را براساس نوع عملیات مرتب کنید (به‌جز عملیات وابسته به یکدیگر که باید به‌طور متوالی در زیردسته‌های اتمی گروه‌بندی شوند). برای مثال، اگر کارتان شامل عملیات افزودن پویش‌های استاندارد، گروه‌های آگهی، و معیارهای گروه آگهی است، عملیات را در بارگذاری‌تان به‌گونه‌ای مرتب کنید که ابتدا همه عملیات پویش، سپس همه عملیات گروه آگهی، و درنهایت همه عملیات معیار گروه آگهی قرار بگیرند.

  • در عملیات‌های یکسان، گروه‌بندی آن‌ها براساس منبع اصلی می‌تواند عملکرد را بهبود بخشد. برای مثال، اگر مجموعه‌ای از اشیاء AdGroupCriterionOperation دارید، گروه‌بندی عملیات براساس گروه آگهی کارآمدتر از ترکیب عملیاتی است که بر معیارهای گروه آگهی در گروه‌های آگهی مختلف تأثیر می‌گذارد.

اتمی بودن در تقسیم دسته‌ای

Google Ads API عملیات را در دسته کار ارسال‌شده به دسته‌های فرعی کوچک‌تر برای پردازش تقسیم می‌کند. درحالی‌که زیردسته‌های استاندارد با فعال بودن شکست جزئی اجرا می‌شوند، زیردسته‌های مربوط به برخی عملیات‌های وابسته به یکدیگر به‌صورت اتمی به‌عنوان یک تراکنش واحد پردازش می‌شوند:

برای هر دو AssetGroup و «عملکرد بیشینه» Campaign زیردسته‌های ایجاد (تا مجموع ۱۰۰۰ عملیات در هر زیردسته؛ هر عملیات فرزند create فراتر از ۹۹۹ به زیردسته غیراتمی بعدی منتقل می‌شود):

  • عملیات create والد (resource_name در AssetGroup یا Campaign) و عملیات‌های create فرزند متوالی آن (asset_group در AssetGroupAsset یا campaign در CampaignAsset) باید شناسه موقت منفی یکسانی را مشخص کنند.
  • Place any prerequisite AssetOperation (create) operations for new Asset resources before the parent AssetGroupOperation or CampaignOperation (create), never between the parent create and its child link create operations (which would immediately close the atomic sub-batch and split the parent resource creation from its linked assets).

وقتی یک زیردسته اتمی ناموفق می‌شود، BatchJobResult.status عملیات متخلف حاوی خطای اعتبارسنجی زیربنایی است، درحالی‌که عملیات باقی‌مانده در آن زیردسته با خطای تراکنش مربوطه برای آن زیردسته بازگردانده می‌شوند. ورودی‌های BatchJobResult مجاور را که دارای شناسه AdGroup، AssetGroup، یا Campaign یکسان هستند بررسی کنید تا علت ریشه‌ای خطا را شناسایی کنید.

اگر عملیات مرتبط در هریک از این گروه‌ها به‌طور متوالی اضافه نشود، Google Ads API آن‌ها را در دسته‌های فرعی جداگانه تقسیم می‌کند، که باعث می‌شود اصلاحیه الزامات حداقل دارایی را برآورده نکند یا درخت‌های گروه فهرستگان ناقص بماند. برای جزئیات، استفاده از فیلترهای گروه فهرستگان در کارهای دسته‌ای و پردازش دسته‌ای «عملکرد بیشینه» را ببینید.

گروه‌بندی منطقی

هنگام اصلاح سلسله‌مراتب هدف‌یابی محصول (AssetGroupListingGroupFilterOperation در پویش‌های «بیشینه‌سازی عملکرد» یا AdGroupCriterionOperation در پویش‌های Shopping) یا ایجاد AssetGroup جدید یا Campaign «بیشینه‌سازی عملکرد»، همه عملیات‌هایی را که منبع اصلی یکسانی را هدف قرار می‌دهند (AssetGroup، AdGroup، یا Campaign) به‌صورت متوالی گروه‌بندی کنید. این کار رقابت قفل باطن را کاهش می‌دهد و درخت‌های وابسته به یکدیگر را باهم نگه می‌دارد.

سازگاری داده‌ها

چون درخت‌های فیلتر گروه فهرستگان و الزامات دارایی «عملکرد بیشینه» در پایان هر تراکنش زیردسته اتمی اعتبارسنجی می‌شوند، از تقسیم کردن به‌روزرسانی‌ها به منبع اصلی یکسان در دامنه‌های ناپیوسته در یک کار یا در کارهای هم‌زمان خودداری کنید.

اجتناب از مشکلات همزمانی

  • هنگام ارسال چندین کار هم‌زمان برای یک حساب، احتمال اجرای کارها روی اشیاء یکسان در یک زمان را کاهش دهید و درعین‌حال اندازه کارهای بزرگ را حفظ کنید. بسیاری از کارهای ناتمام با وضعیت RUNNING که سعی می‌کنند همان مجموعه اشیاء را تغییر دهند می‌توانند منجر به شرایطی شبیه بن‌بست شوند که باعث کندی شدید و حتی شکست کار می‌شود.

  • چندین عملیات را که یک شیء را در یک کار تغییر می‌دهند ارسال نکنید، زیرا نتیجه می‌تواند غیرقابل پیش‌بینی باشد.

بازیابی نتایج به‌صورت بهینه

  • وضعیت کار را بیش‌ازحد مکرر نظرسنجی نکنید، درغیراین‌صورت ممکن است با خطاهای حد نرخ مواجه شوید.

  • هنگام فراخوانی ListBatchJobResults، page_size را تنظیم‌نشده رها کنید (یا آن را روی حداکثر 1000 تنظیم کنید) تا رفت‌وبرگشت‌های صفحه‌بندی را به‌حداقل برسانید، و فقط درصورتی‌که برنامه‌تان فیلدهای منبع برگردانده‌شده را فراتر از resource_name بررسی می‌کند، response_content_type را روی MUTABLE_RESOURCE تنظیم کنید.

  • ترتیب نتایج همان ترتیب بارگذاری است.

راهنمایی‌های بیشتر درباره استفاده

  • می‌توانید حد بالایی برای مدت زمانی که یک کار دسته‌ای مجاز است اجرا شود قبل‌از اینکه لغو شود، تعیین کنید. هنگام ایجاد کار دسته‌ای جدید، فیلد metadata.execution_limit_seconds را روی محدودیت زمانی دلخواهتان (به ثانیه) تنظیم کنید. اگر metadata.execution_limit_seconds تنظیم نشده باشد، محدودیت زمانی پیش‌فرضی وجود ندارد.

  • اگرچه حد مجاز پروتکل ۱۰٬۰۰۰ عملیات در هر درخواست است، توصیه می‌کنیم بیش‌از ۱٬۰۰۰ عملیات در هر AddBatchJobOperationsRequest اضافه نکنید و از sequence_token برای بارگذاری بقیه عملیات‌ها در همان کار استفاده کنید. بسته به اندازه عملیات، ارسال بیش‌ازحد عملیات در یک AddBatchJobOperationsRequest می‌تواند باعث خطای BatchJobError.REQUEST_TOO_LARGE شود. می‌توانید با کاهش تعداد عملیات و تکرار مجدد AddBatchJobOperationsRequest، این خطا را برطرف کنید.

محدودیت‌ها

  • هر BatchJob از حداکثر یک میلیون عملیات پشتیبانی می‌کند. فراتر رفتن از این حد مجاز هنگام فراخوانی AddBatchJobOperations خطای ResourceCountLimitExceededError.RESOURCE_LIMIT را برمی‌گرداند (با ResourceLimitType.BATCH_JOB_OPERATIONS_PER_JOB در ErrorDetails.resource_count_details).

  • هر حساب می‌تواند به‌طور هم‌زمان حداکثر ۱۰۰ کار فعال یا معلق داشته باشد. فراتر رفتن از این حد هنگام ایجاد کار دسته‌ای با MutateBatchJob خطای ResourceCountLimitExceededError.RESOURCE_LIMIT را برمی‌گرداند (با ResourceLimitType.BATCH_JOBS_PER_CUSTOMER در ErrorDetails.resource_count_details).

  • کارهای معلق قدیمی‌تر از ۷ روز به‌طور خودکار برداشته می‌شوند.

  • هر AddBatchJobOperationsRequest حد سخت ۱۰٬۰۰۰ عملیات تغییریافته در هر درخواست دارد. اگر تعداد عملیات‌ها در یک درخواست از ۱۰٬۰۰۰ فراتر برود، خطای BatchJobError.REQUEST_TOO_LARGE برگردانده می‌شود.

  • برای فیلد page_size در ListBatchJobResultsRequest:

    • اگر page_size تنظیم نشده باشد یا 0 باشد، به‌طور پیش‌فرض روی حداکثر 1000 تنظیم می‌شود.
    • اگر page_size از 1000 بیشتر باشد یا از 0 کمتر باشد، API خطای BatchJobError.INVALID_PAGE_SIZE را برمی‌گرداند.

  • هر AddBatchJobOperationsRequest حداکثر ۴۱٬۹۳۷٬۹۲۰ بایت اندازه دارد. اگر از این حد فراتر بروید، خطای BatchJobError.REQUEST_TOO_LARGE (یا INTERNAL_ERROR اگر در لایه انتقال رد شود) دریافت می‌کنید. می‌توانید اندازه سریال‌سازی‌شده درخواست را قبل‌از ارسال تعیین کنید و اگر خیلی بزرگ بود، اقدام مناسب را انجام دهید:

    جاوا

    
static final int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.getSerializedSize();

    C#‎

    
const int MAX_REQUEST_BYTES = 41_937_920;

// ... (code to get the AddBatchJobOperationsRequest object)

int sizeInBytes = request.CalculateSize();

    PHP

    
const MAX_REQUEST_BYTES = 41937920;

// ... (code to get the AddBatchJobOperationsRequest object)

$size_in_bytes = $request->byteSize();

    Python

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = type(request).pb(request).ByteSize()

    Ruby

    
MAX_REQUEST_BYTES = 41_937_920

# ... (code to get the AddBatchJobOperationsRequest object)

size_in_bytes = request.to_proto.bytesize

    پرل

    
use JSON::XS;
use constant MAX_REQUEST_BYTES => 41937920;

# ... (code to get the AddBatchJobOperationsRequest object)

# The Perl client library uses REST/JSON; UTF-8 JSON byte length provides a
# conservative upper-bound estimate of the serialized request size.
my $json_encoder = JSON::XS->new->utf8->convert_blessed;
my $size_in_bytes = length($json_encoder->encode($request));

اندازه عملیات تغییریافته تکی

درحالی‌که کل درخواست می‌تواند تا ۴۱٬۹۳۷٬۹۲۰ بایت باشد، اندازه سریالی‌شده یک MutateOperation در دسته به ۱۰٬۴۸۴٬۵۰۴ بایت (۱۰ مبی‌بایت منهای ۱٬۲۵۶ بایت) محدود شده است. فراتر رفتن از این حد مجاز خطای BatchJobError.REQUEST_TOO_LARGE را برمی‌گرداند. توجه داشته باشید که اگرچه سند مرجع برای BatchJobError.REQUEST_TOO_LARGE به آستانه ۱۰٬۴۸۴٬۵۰۴ بایت اشاره می‌کند، AddBatchJobOperations همین کد خطا را برمی‌گرداند وقتی هریک از سه آستانه درخواست (درمجموع ۴۱٬۹۳۷٬۹۲۰ بایت درخواست، ۱۰٬۴۸۴٬۵۰۴ بایت تک‌عملیات، یا ۱۰٬۰۰۰ عملیات در هر فراخوانی) فراتر رود، با فیلد message خطا که مشخص می‌کند کدام حد نقض شده است.

قبلی
فیلترهای گروه فهرستگان