تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
كما هو موضّح في دليل بنية واجهة برمجة التطبيقات، يتضمّن كل مورد من المستوى الأعلى في Google Ads API خدمة ذات صلة بنوع المورد تتيح تعديل مثيلات المورد.
سيستخدم هذا الدليل CampaignService لتوضيح كيفية تعديل عناصر Campaign، ولكن تنطبق المفاهيم نفسها على جميع الخدمات الأخرى الخاصة بنوع الموارد.
تغيير العناصر
ستتضمّن كل خدمة خاصة بنوع مورد معيّن طريقة mutate تقبل طلبًا لتعديل البيانات. يتألف هذا الطلب من:
customerId
مجموعة من العمليات
إعداد لنوع محتوى الردّ يحدّد ما إذا كان يجب عرض المورد القابل للتغيير أو اسم المورد فقط بعد التغيير.
على سبيل المثال، تقبل الطريقة MutateCampaigns في CampaignServiceMutateCampaignsRequest يتألف من:
customerId
مجموعة من CampaignOperation كائنات
حقل response_content_type الذي يشير إلى نوع الردّ المفضّل
العمليات
يتيح لك عنصر العملية، مثل CampaignOperation، تحديد الإجراء الذي تريد تنفيذه على مورد واحد من خلال ضبط الحقل operation. هذا الحقل هو حقل oneof يتألف من السمات التالية التي يكون نوعها هو نوع المورد:
create
تنشئ هذه الطريقة مثيلاً جديدًا للمورد.
update
تعدّل المرجع ليتطابق مع سمات المرجع update.
عند ضبط هذا الحقل، يجب أيضًا ضبط update_mask للعملية، ما يوضّح لـ Google Ads API السمات التي سيتم تعديلها أثناء عملية التعديل. تحتوي كل مكتبة برامج على أداة أو طريقة مساعدة تنشئ لك update_mask، كما هو موضّح في مكتبات البرامج.
remove
يزيل المورد.
بما أنّ الحقل operation هو حقل oneof، لا يمكنك استخدام عملية واحدة لتعديل عناصر متعددة. على سبيل المثال، إذا كنت تريد إنشاء حملة وإزالة حملة أخرى، أضِف مثيلَين من CampaignOperation إلى طلبك: أحدهما مع ضبط create، والآخر مع ضبط remove.
عمليات مجمعة
على الرغم من أنّ العملية الواحدة يمكنها فقط إنشاء مورد واحد أو تعديله أو إزالته، يمكن أن يحتوي طلب التعديل الواحد على عمليات متعددة. عليك دمج عملياتك في طلب تغيير واحد بدلاً من إرسال طلبات تغيير متعددة يحتوي كل منها على عملية واحدة.
على سبيل المثال، إذا أردت إنشاء عشر حملات، عليك إرسال طلب واحدMutateCampaignsRequest يتضمّن عشرة عناصر CampaignOperation.
تغيير الردود
يعتمد ما يتم عرضه في الاستجابة على ما تم إرساله في response_content_type لطلب التعديل. على سبيل المثال، إذا تم تحديد MUTABLE_RESOURCE، ستتضمّن الاستجابة الحقول القابلة للتعديل في الحملة فقط. يمكنك بعد ذلك إجراء عمليات تغيير لاحقة على عنصر المورد هذا بدون الحاجة إلى إعادة إنشائه.
أخطاء التغيير
لن يتم تطبيق العمليات الواردة في طلب تغيير معيّن على حسابك على "إعلانات Google" إلا إذا نجحت كل عملية في الطلب. اطّلِع على دليل الأخطاء الشائعة للحصول على قائمة بالأخطاء الشائعة وكيفية حلّها.
تاريخ التعديل الأخير: 2025-08-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-26 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eUse the Google Ads API to modify and inspect objects, such as campaigns, through their respective services.\u003c/p\u003e\n"],["\u003cp\u003eEach resource-type-specific service has a mutate method to create, update, or remove instances of that resource type.\u003c/p\u003e\n"],["\u003cp\u003eOperations within a single mutate request are atomic; all operations must succeed for any changes to be applied.\u003c/p\u003e\n"],["\u003cp\u003eBatch multiple operations into a single mutate request for efficiency, instead of sending individual requests.\u003c/p\u003e\n"],["\u003cp\u003eSpecify a response content type to control the data returned in the response, potentially streamlining further interactions.\u003c/p\u003e\n"]]],[],null,["# Change Objects\n\n| **Objective:** Understand how to modify objects using the Google Ads API.\n\nAs discussed in the [API structure guide](/google-ads/api/docs/concepts/api-structure), each\ntop-level resource in the Google Ads API has a corresponding resource-type-specific\nservice that supports modifying instances of the resource.\n\nThis guide will use [`CampaignService`](/google-ads/api/reference/rpc/v21/CampaignService) to\ndemonstrate modifying [`Campaign`](/google-ads/api/reference/rpc/v21/Campaign)\nobjects, but the same concepts apply to all other resource-type-specific\nservices.\n| **Key Term:** A top-level resource is a [resource](/google-ads/api/reference/rpc/v21/overview#resources) whose name does not include a period (`.`). For example, `Campaign` is a top-level resource, but `Campaign.NetworkSettings` is not.\n\nChange objects\n--------------\n\nEach resource-type-specific service will have a *mutate* method that accepts\na mutate request. This request consists of:\n\n- A `customerId`\n- A collection of operations\n- A response content-type setting that determines whether the mutable resource or just the resource name should be returned post mutation.\n\nFor example, the `MutateCampaigns` method of `CampaignService` accepts a\n[`MutateCampaignsRequest`](/google-ads/api/reference/rpc/v21/MutateCampaignsRequest) that consists\nof:\n\n- A `customerId`\n- A collection of `CampaignOperation` objects\n- The `response_content_type` field indicating the preferred response type.\n\n### Operations\n\nAn operation object such as a `CampaignOperation` lets you specify the\naction that you want to perform on a single resource by setting its `operation`\nfield. This field is a\n[oneof field](//protobuf.dev/programming-guides/proto3/#oneof)\nconsisting of the following attributes whose type is the resource type:\n\n`create`\n: Creates a new instance of the resource.\n\n`update`\n: Updates the resource to match the attributes of the `update` resource.\n When this field is set, you must also set the `update_mask` of the\n operation, which tells the Google Ads API which attributes to modify during\n the update operation. Each [client library](/google-ads/api/docs/client-libs) has a\n utility or helper method that will generate the `update_mask` for you, as\n demonstrated in our [client libraries](/google-ads/api/docs/client-libs).\n\n`remove`\n: Removes the resource.\n\nSince the `operation` field is a `oneof` field, you cannot use a single\noperation to modify multiple objects. For example, if you want to create one\ncampaign and remove another campaign, add two instances of `CampaignOperation`\nto your request: one with `create` set, and another with `remove` set.\n\n### Batch operations\n\nAlthough a single operation can only either create, update, or remove a single\nresource, a single mutate request can contain multiple operations. You should\ncombine your operations into a single mutate request instead of sending multiple\nmutate requests that each contain a single operation.\n\nFor example, if you want to create ten campaigns, you should send a\n*single* `MutateCampaignsRequest` that has ten `CampaignOperation` objects.\n\n### Mutate responses\n\nWhat is returned in the response depends on what was sent in the\n[`response_content_type`](/google-ads/api/reference/rpc/v21/ResponseContentTypeEnum.ResponseContentType)\nof the mutate request. For example, if `MUTABLE_RESOURCE` was specified, then\nthe [response](/google-ads/api/reference/rpc/v21/MutateCampaignsResponse) would contain just the\nmutable fields in the campaign. You can then make follow-up mutates on that\nresource object without having to reconstruct it.\n\n### Mutate errors\n\nThe operations in a given mutate request will only be applied to your Google Ads\naccount if *every* operation in the request succeeds. Check out the\n[common errors guide](/google-ads/api/docs/common-errors) for a list of common\nerrors and how to address them."]]
