جهش

جاوااسکریپت Google Ads از جهش‌های عمومی که در Google Ads API دردسترس است پشتیبانی می‌کند. بیشتر عملیاتی که می‌توان از GoogleAdsService.mutate انجام داد، ازجمله ایجاد و مدیریت پویش‌ها، در جاوااسکریپت Google Ads نیز قابل انجام است.

ازآنجایی‌که این ویژگی امکان دسترسی به بخش بزرگی از Google Ads API را فراهم می‌کند، مهم است که برای استفاده از این ویژگی، درک پایه‌ای از قراردادهای Google Ads API داشته باشید. بسیاری از جنبه‌ها را می‌توان نادیده گرفت، مانند توکن‌های توسعه‌دهنده و مجوز، زیرا این موارد توسط جاوااسکریپت Google Ads برای شما مدیریت می‌شوند، اما باید یک درخواست تغییر معتبر ایجاد کنید.

در اینجا چند منبع اصلی درباره میانای Google Ads API REST وجود دارد که باید قبل‌از ادامه این راهنما با آن‌ها آشنا شوید:

نمونه پایه

برای نشان دادن عملکرد، این مثال ساده را که بودجه پویش ایجاد می‌کند درنظر بگیرید:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

فراخوانی AdsApp.mutate یک شیء JSON را می‌گیرد که نشان‌دهنده یک MutateOperation است. در این شیء، مشخص می‌کنید که چه نوع عملیاتی را انجام می‌دهید—در این مورد، campaignBudgetOperation. سپس create، remove، یا هر دو update و updateMask را مشخص می‌کنید. فیلدهای خاص در create و update به نوع خاص منبعی که روی آن کار می‌کنید بستگی دارد.

ساختن عملیات

چند استراتژی وجود دارد که می‌توانید برای ساختن یک عملیات معتبر استفاده کنید. با ادامه دادن مثال بودجه پویش، می‌توانید سند مرجع REST برای بودجه پویش را جستجو کنید تا فهرستی از همه فیلدهای معتبر آن را ببینید و سپس فیلدهای مناسب را تکمیل کنید، یا کد جاوا اسکریپت سفارشی در اسکریپت خود بنویسید تا شیء مناسبی بسازید.

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

انواع عملیات

ایجاد کردن

create را در عملیات خود مشخص کنید و نمایش شیء منبعی را که می‌خواهید ایجاد کنید ارسال کنید.

برای نمونه‌ای از عملیات create، به قطعه‌کدی که قبلاً ارائه شده است مراجعه کنید.

برداشتن

remove را در عملیات خود مشخص کنید و نام منبع منبعی را که می‌خواهید بردارید وارد کنید، برای مثال:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

اگر نام منبع را برای موجودیتی نمی‌دانید، می‌توانید آن را بااستفاده از درخواست Adsapp.search واکشی کنید.

به‌روزرسانی

update را در عملیات خود مشخص کنید و شیء را با نام منبع مشخص‌شده ارسال کنید تا سیستم بتواند تعیین کند کدام شیء را می‌خواهید به‌روز کنید. علاوه‌براین، هر فیلدی را که می‌خواهید مقادیر آن را به‌روز کنید تکمیل کنید و یک updateMask مشخص کنید که دقیقاً نشان می‌دهد قصد دارید کدام فیلدها را در این درخواست تغییر دهید. نام منبع را در ماسک به‌روزرسانی وارد نکنید.

نمونه‌ای از عملیات update:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

نتایج نام کاربری

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

در اینجا مثالی آورده شده است که جریان پایه‌ای را برای بررسی نتیجه و چاپ برخی اطلاعات در گزارش‌ها نشان می‌دهد:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

چندین عملیات

جاوااسکریپت Google Ads همچنین از تغییر چندین عملیات در یک درخواست با روش AdsApp.mutateAll پشتیبانی می‌کند. می‌توانید نهادهایی را که به یکدیگر وابسته هستند، مانند سلسله مراتب کامل پویش، در یک درخواست ایجاد کنید. می‌توانید به‌صورت اختیاری کل مجموعه عملیات را اتمی کنید، بنابراین اگر یکی از آن‌ها ناموفق باشد، هیچ‌کدام انجام نمی‌شوند.

مقدار برگشتی آرایه‌ای از اشیاء MutateResult است، یکی برای هر عملیاتی که ارائه کرده‌اید و با همان ترتیبی که در عملیات اولیه وجود دارد.

این ویژگی عملکردی مشابه ویژگی Google Ads API دارد، بنابراین برای توضیح کامل شناسه‌های موقت و سایر ملاحظات، به راهنمای روال‌های مطلوب Google Ads API مراجعه کنید؛ توجه داشته باشید که این راهنما از snake_case برای نمایش نام فیلدها استفاده می‌کند، درحالی‌که اسناد جاوااسکریپت Google Ads از lowerCamelCase استفاده می‌کند. هر دو مورد در جاوااسکریپت Google Ads پذیرفته می‌شوند، بنابراین می‌توانید کد را مستقیماً از آن راهنما کپی کنید.

برای انجام چندین عملیات در یک درخواست، همه عملیات‌هایتان را در یک آرایه جمع‌آوری کنید و سپس AdsApp.mutateAll را فراخوانی کنید. فراخوانی mutateAll آرایه عملیات را به‌عنوان اولین آرگومان و آرگومان دوم اختیاری گزینه‌ها، ازجمله موارد زیر، می‌گیرد:

  • apiVersion: می‌توانید نسخه سفارشی میانای برنامه‌سازی کاربردی را مشخص کنید، مثلاً V26، اگر می‌خواهید از نسخه‌ای غیراز پیش‌فرض اسکریپت‌ها استفاده کنید. می‌توانید از هر نسخه‌ای که در آن زمان به‌طور عمومی دردسترس است استفاده کنید.
  • partialFailure: این فیلد به‌طور پیش‌فرض روی true تنظیم شده است. اگر روی true تنظیم شده باشد، عملیات معتبر انجام می‌شود و عملیات ناموفق خطا برمی‌گرداند. اگر روی false تنظیم شود، درصورت ناموفق بودن هر عملیاتی، هیچ عملیاتی انجام نمی‌شود و این مجموعه عملیات به‌طور مؤثر تجزیه‌ناپذیر می‌شود.

در اینجا مثالی با چند عملیات آورده شده است که بودجه پویش، پویش، و گروه آگهی را در یک درخواست اتمی ایجاد می‌کند.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});