تبديل

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