جهش

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

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

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

• طراحی میانای REST
• نام‌های منبع
• نگاشت‌های JSON
• Mutate

نمونه پایه

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

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: اگر می‌خواهید از نسخه‌ای غیر از نسخه پیش‌فرض نوشتارها استفاده کنید، می‌توانید نسخه سفارشی API را مشخص کنید، مثلاً 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});