جهش پیدا کند

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

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

در اینجا چند منبع اساسی در مورد رابط کاربری REST API گوگل ادز وجود دارد که قبل از ادامه این راهنما باید با آنها آشنا باشید:

مثال پایه

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

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

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

ساخت یک عملیات

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

از طرف دیگر، می‌توانید با استفاده از ویژگی "Try this" برای campaign budget ، یک عملیات را به صورت پویا بسازید، که به شما امکان می‌دهد با انتخاب فیلدهایی که می‌خواهید اضافه کنید، یک بدنه درخواست را به صورت پویا بسازید. سپس می‌توانید محتویات عملیات را از نتیجه تولید شده استخراج کرده و پس از مشخص کردن نوع عملیات، آن را به فراخوانی mutate خود اضافه کنید.

انواع عملیات

ایجاد

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

برای مثالی از عملیات create به قطعه کد ارائه شده قبلی مراجعه کنید.

حذف

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

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

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

به‌روزرسانی

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

مثالی از عملیات 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);
    }
}

عملیات چندگانه

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

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

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

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

  • apiVersion : اگر مایل به استفاده از نسخه‌ای غیر از نسخه پیش‌فرض اسکریپت‌ها هستید، می‌توانید یک نسخه API سفارشی، مانند V23 ، مشخص کنید. می‌توانید از هر نسخه عمومی موجود در آن زمان استفاده کنید.
  • 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});