Method: customers.googleAds.mutate

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

هذه الطريقة هي في الأساس برنامج تضمين حول سلسلة من الطرق mutate. الميزات الوحيدة المتوفرة عبر استدعاء هذه الطرق مباشرةً هي:

  • المعاملات الصغيرة
  • أسماء الموارد المؤقتة (الموضّحة أدناه)
  • تقليل وقت الاستجابة نوعًا ما على إجراء سلسلة من الطلبات المتغيرة

ملاحظة: يتم فقط تضمين الموارد التي تتيح المعاملات البسيطة، لذلك لا يمكن أن تستبدل هذه الطريقة جميع المكالمات إلى الخدمات الفردية.

مزايا المعاملات عبر Atom

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

أسماء الموارد المؤقتة

أسماء الموارد المؤقتة هي نوع خاص من أسماء الموارد المستخدمة لإنشاء مورد والإشارة إلى هذا المورد في الطلب نفسه. على سبيل المثال، إذا تم إنشاء ميزانية حملة بقيمة resourceName تساوي customers/123/campaignBudgets/-1، يمكن إعادة استخدام اسم هذا المورد في الحقل Campaign.budget في الطلب نفسه. بهذه الطريقة، يتم إنشاء المصدرين وربطهما بشكل هرمي.

لإنشاء اسم مورد مؤقت، ضع رقمًا سالبًا في جزء الاسم الذي يخصصه الخادم عادةً.

ملاحظة:

  • يجب إنشاء الموارد باسم مؤقت قبل إعادة استخدام الاسم. على سبيل المثال، سيتعذّر تنفيذ المثال السابق على CampaignBudget+Campaign إذا تم عكس ترتيب التغيير.
  • لا يتم تذكُّر الأسماء المؤقتة على مستوى الطلبات.
  • وما من حدّ أقصى لعدد الأسماء المؤقتة في الطلب.
  • يجب أن يستخدم كل اسم مؤقت رقمًا سالبًا فريدًا، حتى إذا اختلفت أنواع الموارد.

وقت الاستجابة

من المهم تجميع عمليات التبديل حسب نوع المورد وإلا قد تنتهي مهلة الطلب وتفشل. يساوي وقت الاستجابة تقريبًا سلسلة من الطلبات لطرق التبديل الفردية، حيث يكون كل تغيير في نوع المورد استدعاءً جديدًا. على سبيل المثال، عند تغيير 10 حملات ثم 10 مجموعات إعلانية، يشبه إجراء مكالمتَين مكالمتَين، في حين أنّ تغيير حملة واحدة ومجموعة إعلانية واحدة وحملة واحدة ومجموعة إعلانية واحدة يشبه إجراء 4 مكالمات.

{AdGroupError1Error1{1Error#Name حديثًا{AdSourceError AdError AdGroupAdError AdGroupCriterionError AdGroupErrorAuthenticationError AuthorizationError BiddingErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

طلب HTTP

POST https://googleads.googleapis.com/v14/customers/{customerId}/googleAds:mutate

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

مَعلمات المسار

المَعلمات
customerId

string

مطلوبة. رقم تعريف العميل الذي يتم تعديل موارده.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "mutateOperations": [
    {
      object (MutateOperation)
    }
  ],
  "partialFailure": boolean,
  "validateOnly": boolean,
  "responseContentType": enum (ResponseContentType)
}
الحقول
mutateOperations[]

object (MutateOperation)

مطلوبة. قائمة العمليات المطلوب تنفيذها على الموارد الفردية.
partialFailure

boolean

في حال ضبط هذه السياسة على "صحيح"، سيتم تنفيذ عمليات ناجحة، وستعرض العمليات غير الصالحة أخطاء. وفي حال اختيار القيمة "false"، سيتم تنفيذ جميع العمليات في معاملة واحدة فقط إذا كانت كلها صالحة. القيمة التلقائية هي "خطأ".
validateOnly

boolean

إذا كانت القيمة true، يتم التحقق من صحة الطلب ولكن لا يتم تنفيذه. يتم عرض الأخطاء فقط وليس النتائج.
responseContentType

enum (ResponseContentType)

إعدادات نوع محتوى الردّ تحدِّد هذه السمة ما إذا كان يجب عرض المورد القابل للتغيير أو اسم المورد فقط بعد التبديل. سيتم عرض المورد القابل للتغيير فقط إذا كان المورد يحتوي على حقل الاستجابة المناسب. على سبيل المثال، MutateCampaignResult.campaign.

نص الاستجابة

رسالة الرد على GoogleAdsService.Mutate.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "partialFailureError": {
    object (Status)
  },
  "mutateOperationResponses": [
    {
      object (MutateOperationResponse)
    }
  ]
}
الحقول
partialFailureError

object (Status)

الأخطاء التي تتعلّق بحالات تعذُّر التشغيل في وضع الفشل الجزئي. يُعرَض فقط عندما تكون قيمة جزئية Failrelure = true وتكون جميع الأخطاء داخل العمليات. في حالة حدوث أي أخطاء خارج العمليات (على سبيل المثال، أخطاء المصادقة)، يتم عرض خطأ على مستوى استدعاء إجراء عن بُعد (RPC).
mutateOperationResponses[]

object (MutateOperationResponse)

جميع الردود الخاصة بالمتغير

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/adwords

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.