جهش پیدا کند

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

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

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

• طراحی رابط REST
• نام منابع
• نقشه برداری JSON
• جهش پیدا کند

مثال اساسی

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

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 سفارشی، مانند V18 را مشخص کنید. در آن زمان می توانید از هر نسخه ای که برای عموم در دسترس است استفاده کنید.
• 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});