تبديل

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

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

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

مثال أساسي

لتوضيح الوظيفة، انظر في المثال الأساسي التالي الذي ينشئ ميزانية للحملة:

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