Method: customers.googleAds.mutate

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

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

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

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

مزايا المعاملات البسيطة

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

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

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

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

ملاحظة:

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

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

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

{ AdGroupAdError AdGroupCriterionErrorCampaignBudgetErrorCampaignCriterionErrorCampaignErrorCampaignExperimentErrorCampaignSharedSetErrorCollectionSizeErrorContextErrorConversionActionErrorCriterionErrorCustomerFeedErrorDatabaseErrorDateErrorDateRangeErrorDistinctErrorExtensionFeedItemErrorExtensionSettingErrorFeedAttributeReferenceErrorFeedErrorFeedItemErrorFeedItemSetErrorFieldErrorFieldMaskErrorFunctionParsingErrorHeaderErrorImageErrorInternalErrorKeywordPlanAdGroupKeywordErrorKeywordPlanCampaignErrorKeywordPlanErrorLabelErrorListOperationErrorMediaUploadErrorMutateErrorNewResourceCreationErrorNullErrorOperationAccessDeniedErrorPolicyFindingErrorPolicyViolationErrorQuotaErrorRangeErrorRequestErrorResourceCountLimitExceededErrorSettingErrorSharedSetErrorSizeLimitErrorStringFormatErrorStringLengthErrorUrlFieldErrorUserListErrorYoutubeVideoRegistrationError

طلب HTTP

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

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

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

المَعلمات
customerId

string

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

نص الطلب

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

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

object (MutateOperation)

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

boolean

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

boolean

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

enum (ResponseContentType)

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

نص الاستجابة

رسالة الرد لـ "GoogleAdsService.Mutate".

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

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

object (Status)

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

object (MutateOperationResponse)

جميع الردود المتعلّقة بعملية التبديل.

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

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

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

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