تبديل

تتيح النصوص البرمجية في "إعلانات 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});