تبديل

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

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

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

مثال أساسي

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

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