بهترین شیوه ها و محدودیت ها

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

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

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

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

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

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

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

برای هر دو زیرگروه ایجاد Campaign AssetGroup و Performance Max (حداکثر ۱۰۰۰ عملیات در هر زیرگروه؛ هر عملیات create فرزند فراتر از ۹۹۹ به زیرگروه غیر اتمی بعدی منتقل می‌شود):

  • عملیات create والد ( resource_name روی AssetGroup یا Campaign ) و عملیات create فرزند متوالی آن ( asset_group روی AssetGroupAsset یا campaign روی CampaignAsset ) باید شناسه موقت منفی یکسانی را مشخص کنند.
  • هرگونه عملیات پیش‌نیاز AssetOperation ( create ) برای منابع Asset جدید را قبل از AssetGroupOperation والد یا CampaignOperation ( create ) قرار دهید، هرگز بین create والد و عملیات create پیوند فرزند آن قرار ندهید (که بلافاصله زیرگروه اتمی را می‌بندد و ایجاد منبع والد را از دارایی‌های پیوند شده‌اش جدا می‌کند).

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

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

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

هنگام تغییر سلسله مراتب هدف‌گیری محصول ( AssetGroupListingGroupFilterOperation در کمپین‌های Performance Max یا AdGroupCriterionOperation در کمپین‌های Shopping) یا ایجاد یک AssetGroup یا Performance Max Campaign جدید، تمام عملیاتی را که منبع والد یکسانی ( AssetGroup ، AdGroup یا Campaign ) را هدف قرار می‌دهند، به صورت متوالی گروه‌بندی کنید. این کار باعث کاهش تداخل قفل در backend و حفظ یکپارچگی درخت‌های وابسته به هم می‌شود.

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

از آنجا که فهرست‌بندی درخت‌های فیلتر گروهی و الزامات دارایی‌های Performance Max در پایان هر تراکنش زیر-دسته‌ای اتمی اعتبارسنجی می‌شوند، از تقسیم به‌روزرسانی‌ها به همان منبع والد در محدوده‌های ناپیوسته در یک کار یا در کارهای همزمان خودداری کنید.

از مشکلات همزمانی جلوگیری کنید

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

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

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

  • وضعیت کار را خیلی مرتب بررسی نکنید، وگرنه با خطاهای مربوط به محدودیت نرخ مواجه می‌شوید.

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

  • ترتیب نتایج مشابه ترتیب آپلود است.

راهنمایی استفاده اضافی

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

  • اگرچه محدودیت پروتکل ۱۰۰۰۰ عملیات در هر درخواست است، اما توصیه می‌کنیم بیش از ۱۰۰۰ عملیات در هر AddBatchJobOperationsRequest اضافه نکنید و از sequence_token برای آپلود بقیه عملیات به همان job استفاده کنید. بسته به اندازه عملیات، ارسال عملیات زیاد در یک 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();

    سی شارپ 

    
const int MAX_REQUEST_BYTES = 41_937_920;

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

int sizeInBytes = request.CalculateSize();

    پی اچ پی 

    
const MAX_REQUEST_BYTES = 41937920;

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

$size_in_bytes = $request->byteSize();

    پایتون 

    
MAX_REQUEST_BYTES = 41_937_920

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

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

    روبی 

    
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 خطا مشخص می‌کند که کدام محدودیت نقض شده است.

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