با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
همانطور که در راهنمای ساختار API بحث شد، هر منبع سطح بالا در Google Ads API دارای یک سرویس مربوط به نوع منبع است که از اصلاح نمونه‌های منبع پشتیبانی می‌کند.
این راهنما از CampaignService برای نشان دادن تغییر اشیاء Campaign استفاده می‌کند، اما مفاهیم مشابه برای سایر سرویس‌های نوع منبع خاص اعمال می‌شود.
اشیاء را تغییر دهید
هر سرویس خاص نوع منبع دارای یک متد جهش است که درخواست جهش را می پذیرد. این درخواست عبارت است از:
customerId
مجموعه ای از عملیات
یک تنظیم نوع محتوای پاسخ که تعیین می کند آیا منبع قابل تغییر یا فقط نام منبع باید جهش پست را برگرداند.
به عنوان مثال، روش MutateCampaigns در CampaignService یک MutateCampaignsRequest می پذیرد که شامل موارد زیر است:
customerId
مجموعه ای از اشیاء CampaignOperation
فیلد response_content_type نشان دهنده نوع پاسخ ترجیحی است.
عملیات
یک شی عملیاتی مانند CampaignOperation به شما امکان می دهد با تنظیم فیلد operation آن، اقدامی را که می خواهید روی یک منبع انجام دهید مشخص کنید. این فیلد یکی از فیلدهای متشکل از ویژگی های زیر است که نوع آن نوع منبع است:
create
یک نمونه جدید از منبع ایجاد می کند.
update
منبع را برای مطابقت با ویژگی های منبع update به روز می کند. وقتی این فیلد تنظیم شد، باید update_mask عملیات را نیز تنظیم کنید، که به API Google Ads می گوید کدام ویژگی ها را در طول عملیات به روز رسانی تغییر دهد. هر کتابخانه سرویس گیرنده دارای یک روش کاربردی یا کمکی است که update_mask برای شما ایجاد می کند، همانطور که در کتابخانه های مشتری ما نشان داده شده است.
remove
منبع را حذف می کند.
از آنجایی که فیلد operationoneof فیلدها است، نمی توانید از یک عملیات واحد برای اصلاح چندین شیء استفاده کنید. به عنوان مثال، اگر می‌خواهید یک کمپین ایجاد کنید و کمپین دیگری را حذف کنید، دو نمونه از CampaignOperation را به درخواست خود اضافه کنید: یکی با مجموعه create و دیگری با مجموعه remove .
عملیات دسته ای
اگرچه یک عملیات تنها می‌تواند یک منبع را ایجاد، به‌روزرسانی یا حذف کند، یک درخواست جهش می‌تواند شامل چندین عملیات باشد. شما باید به جای ارسال چندین درخواست جهش که هر کدام شامل یک عملیات واحد هستند، عملیات خود را در یک درخواست جهش واحد ترکیب کنید.
برای مثال، اگر می‌خواهید ده کمپین ایجاد کنید، باید یکMutateCampaignsRequest ارسال کنید که دارای ده شیء CampaignOperation باشد.
پاسخ ها را تغییر دهید
آنچه در پاسخ بازگردانده می شود بستگی به آنچه در response_content_type درخواست جهش ارسال شده است. برای مثال، اگر MUTABLE_RESOURCE مشخص شده بود، پاسخ فقط شامل فیلدهای قابل تغییر در کمپین خواهد بود. سپس می‌توانید جهش‌های بعدی را در آن شی منبع بدون نیاز به بازسازی آن ایجاد کنید.
جهش خطاها
عملیات در یک درخواست جهش داده شده تنها در صورتی برای حساب Google Ads شما اعمال می شود که هر عملیات در درخواست موفقیت آمیز باشد. راهنمای خطاهای رایج را برای لیستی از خطاهای رایج و نحوه رسیدگی به آنها بررسی کنید.
تاریخ آخرین به‌روزرسانی 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."]]
