تبديل

تتيح نصوص "إعلانات Google" البرمجية إمكانية إجراء عمليات تعديل عامة متوفّرة في الـ Google Ads API. يمكن أيضًا تنفيذ معظم العمليات التي يمكن إجراؤها من GoogleAdsService.mutate في نصوص "إعلانات Google" البرمجية، بما في ذلك إنشاء الحملات وإدارتها.

بما أنّ هذه الميزة تتيح الوصول إلى جزء كبير من Google Ads API، من المهم أن يكون لديك فهم أساسي لاتفاقيات Google Ads API لاستخدام هذه الميزة. يمكنك تخطّي العديد من الجوانب، مثل الرموز المميزة للمطوّرين والمصادقة، لأنّ نصوص "إعلانات Google" البرمجية تتولّى معالجتها نيابةً عنك، ولكن عليك إنشاء طلب تعديل صالح.

في ما يلي بعض المراجع الأساسية حول واجهة 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 لميزانية الحملة للاطّلاع على قائمة بجميع حقولها الصالحة، ثم ملء الحقول المناسبة، أو كتابة رمز JavaScript مخصّص في البرنامج النصي لإنشاء كائن مناسب.

بدلاً من ذلك، يمكنك محاولة إنشاء عملية بشكلٍ ديناميكي باستخدام ميزة "تجربة هذه الميزة" لميزانية الحملة، والتي تتيح لك إنشاء نص طلب بشكلٍ ديناميكي عن طريق اختيار الحقول التي تريد إضافتها. يمكنك بعد ذلك استخراج محتوى العملية من النتيجة التي تم إنشاؤها وإضافته إلى طلب 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" البرمجية أيضًا تعديل عمليات متعدّدة في طلب واحد باستخدام طريقة AdsApp.mutateAll. يمكنك إنشاء كيانات تعتمد على بعضها البعض، مثل تسلسل هرمي كامل للحملة في طلب واحد. يمكنك اختياريًا جعل مجموعة العمليات بأكملها ذرّية، لذا إذا فشلت أي عملية، لن يتم تنفيذ أي منها.

القيمة المعروضة هي مصفوفة من MutateResult كائنات، واحد لكل عملية قدّمتها وبالترتيب نفسه للعمليات الأولية.

تعمل هذه الميزة بالطريقة نفسها التي تعمل بها ميزة Google Ads API، لذا يُرجى الرجوع إلى دليل أفضل ممارسات Google Ads API للحصول على شرح كامل لمعرّفات التتبّع المؤقتة والاعتبارات الأخرى. يُرجى العِلم أنّ الدليل يستخدم snake_case لتمثيل أسماء الحقول، بينما تستخدم مستندات "برامج إعلانات Google النصية" lowerCamelCase. يتم قبول كلتا الحالتَين في نصوص "إعلانات Google" البرمجية، لذا يمكنك نسخ الرمز مباشرةً من هذا الدليل.

لإجراء عمليات متعدّدة في طلب واحد، اجمَع كل عملياتك في مصفوفة ثم استخدِم طريقة AdsApp.mutateAll. يأخذ طلب mutateAll مصفوفة العمليات كمعلَمة أولى ومعلَمة ثانية اختيارية للخيارات، بما في ذلك:

• apiVersion: يمكنك تحديد إصدار مخصّص من واجهة برمجة التطبيقات، مثل V24، إذا كنت تريد استخدام إصدار آخر غير الإصدار التلقائي للبرامج النصية. يمكنك استخدام أي إصدار متاح للجمهور في ذلك الوقت.
• 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});