تبديل

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

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

في ما يلي بعض المراجع الأساسية حول واجهة REST في Google Ads API التي يجب أن تكون على دراية بها قبل مواصلة قراءة هذا الدليل:

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