احتیاط: شما در حال مشاهده اسناد رابط REST API هستید. اکثر کتابخانه های مشتری رسمی ما از gRPC استفاده می کنند. برای جزئیات بیشتر به مقدمه REST مراجعه کنید.
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
سلسله مراتب نام
نام منابع مورد استفاده در Google Ads API سلسله مراتبی است و سازماندهی موجودیت ها در Google Ads را منعکس می کند. تقریباً همه منابع، منابع فرعی منبع Customer هستند، که نشان دهنده این واقعیت است که تقریباً هر تماس API باید یک حساب Google Ads خاص را هدف قرار دهد. برای مثال، کمپین‌ها، گروه‌های تبلیغاتی، تبلیغات و کلمات کلیدی همگی منابع فرعی یک منبع مشتری ریشه هستند.
نهادهای تبلیغاتی گوگل (مشتریان، کمپین ها، و غیره) با نام منابع خود در سراسر API شناخته می شوند. با این حال، توجه به این نکته مهم است که نام منابع خود ممکن است دارای شناسه های عددی منحصر به فردی باشد که هر شیء را در سلسله مراتب شناسایی می کند. در این موارد، تجزیه نام منبع برای استخراج این شناسه های منبع و مونتاژ یک شناسه جدید ممکن است مفید باشد.
به عنوان مثال، نام منبع AdGroupAd را از جدول قبلی بررسی کنید:
این را می توان به شناسه های منبع فردی آن (که با شناسه های مجموعه از هم جدا شده اند) به شرح زیر تقسیم کرد:
اجزای نام منبع
شناسه های منابع
شناسه مشتری:
"1234567890"
شناسه گروه تبلیغات:
"54321098765"
شناسه آگهی گروه تبلیغات:
"2109876543210"
شناسه های مجموعه
"customers"
"adGroupAds"
تجزیه شناسه‌های فردی به شما امکان می‌دهد نام‌های منابع جدیدی را برای ارجاع به مشتری آگهی گروه آگهی ( customers/1234567890 ) یا گروه تبلیغات آن ( customers/1234567890/adGroupAds/54321098765 ) استخراج کنید.
شناسه اشیاء مشترک
بیشتر اشیاء در API با یک مشتری خاص Google Ads مرتبط هستند. با این حال، برخی از انواع شی وجود دارد که می توان آنها را بین چندین حساب به اشتراک گذاشت. در عمل، اینها مواردی مانند لیست کلمات کلیدی منفی یا اقدامات تبدیل بین حساب‌ها هستند که معمولاً توسط مدیران ایجاد می‌شوند و سپس با بسیاری از حساب‌های مشتری به اشتراک گذاشته می‌شوند.
نام منابع اشیایی مانند اینها متفاوت خواهد بود، بسته به این که به چه حسابی تماس API را ارسال می کنید.
مثال: اقدامات تبدیل بین حساب
فرض کنید حساب مدیر 987-654-3210 داریم که یک اقدام تبدیل بین حساب را با یکی از حساب های مشتری مشتری خود 123-456-7890 به اشتراک می گذارد:
برای مثال، برقراری یک تماس API با حساب مدیر برای به‌روزرسانی پنجره بازبینی کنش تبدیل، به شی مشترک با استفاده از نام منبع ارجاع می‌دهد: customers/9876543210/conversionActions/257733534 .
برقراری تماس API با حساب مشتری برای انتخاب استفاده از اقدام تبدیل مشترک، با استفاده از نام منبع به آن ارجاع می دهد: customers/1234567890/conversionActions/257733534 .
این همان عمل تبدیل زیربنایی است، اما نام منبع آن نسبت به حساب مورد استفاده برای دسترسی به آن است.
تاریخ آخرین به‌روزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2025-09-03 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eGoogle Ads API resource names are hierarchical, reflecting the Google Ads account structure, with most resources being sub-resources of the \u003ccode\u003eCustomer\u003c/code\u003e resource.\u003c/p\u003e\n"],["\u003cp\u003eResource names contain unique numerical IDs that identify each object within the hierarchy and can be parsed to derive new resource names.\u003c/p\u003e\n"],["\u003cp\u003eResource names are represented by the \u003ccode\u003eresourceName\u003c/code\u003e field in JSON request/response bodies.\u003c/p\u003e\n"],["\u003cp\u003eShared objects, like negative keyword lists, have resource names relative to the account used to access them, differing between manager and client accounts.\u003c/p\u003e\n"]]],["The Google Ads API employs a hierarchical structure for resource names, with most resources being sub-resources of the `Customer`. Resource names are relative, using a format like `customers/1234567890/campaigns/8765432109`. Entities are identified by unique numerical resource IDs, extractable from resource names. Shared objects like conversion actions have different resource names depending on the accessing account, reflecting a relative association. API requests and responses use the `resourceName` field.\n"],null,["# Resource Names\n\nName hierarchy\n--------------\n\nResource names used in the Google Ads API are hierarchical, mirroring the\norganization of entities within Google Ads. Almost all resources are sub-resources\nof the [`Customer`](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads/v21/resources/customer.proto)\nresource, which reflects the fact that almost every API call has to target a\nspecific Google Ads account. For example, campaigns, ad groups, ads, and keywords\nare all sub-resources of a root customer resource.\n\n| Resource | Resource Name |\n|-----------|-------------------------------------------------------------|\n| Customer | `customers/1234567890` |\n| Campaign | `customers/1234567890/campaigns/8765432109` |\n| AdGroup | `customers/1234567890/adGroups/54321098765` |\n| AdGroupAd | `customers/1234567890/adGroupAds/54321098765~2109876543210` |\n\n| **Key Point:** Google Ads API uses [*relative* resource names](//cloud.google.com/apis/design/resource_names#relative_resource_name) (and not [*full* resource names](//cloud.google.com/apis/design/resource_names#full_resource_name) like some other Google APIs).\n\nResource IDs\n------------\n\nGoogle Ads entities (customers, campaigns, etc.) are referred to by their resource\nnames throughout the API. However, it's important to note that the resource\nnames themselves may have unique numerical [resource\nIDs](//cloud.google.com/apis/design/resource_names#resource_id) that identify\neach object in the hierarchy. In these cases, it may be useful to parse the\nresource name to extract these resource IDs and assemble a new one.\n\nFor example, examine the `AdGroupAd` resource name from the previous table: \n\n customers/1234567890/adGroupAds/54321098765~2109876543210\n\nThis can be broken down into its individual resource IDs (separated by\n[collection IDs](//cloud.google.com/apis/design/resource_names#collection_id))\nas follows:\n\n| Resource name components ||\n|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Resource IDs** | |-----------------|-------------------| | customer ID: | `\"1234567890\"` | | ad group ID: | `\"54321098765\"` | | ad group ad ID: | `\"2109876543210\"` | |\n| **Collection IDs** | |----------------| | `\"customers\"` | | `\"adGroupAds\"` | |\n\nParsing the individual IDs lets you derive new resource names to reference\nthe ad group ad's customer (`customers/1234567890`) or its ad group\n(`customers/1234567890/adGroupAds/54321098765`).\n| **Key Point:** Resource names in JSON request and response bodies are referred to by the `resourceName` field, not the [`name`](//cloud.google.com/apis/design/resource_names#q_why_is_the_special_field_called_name_instead_of_id) field like in some other Google Cloud APIs. Many Google Ads entities have name attributes themselves (`campaign.Name`, `adGroup.Name`, etc.), so `resourceName` is used to avoid collision with existing object names.\n\nIdentifiers of shared objects\n-----------------------------\n\nMost objects in the API are associated with a single specific Google Ads\ncustomer. However, there are some object types that can be shared between\nmultiple accounts. In practice, these are things like [negative keyword\nlists](//support.google.com/google-ads/answer/7519927) or [cross-account\nconversion actions](//support.google.com/google-ads/answer/3030657) that are\nusually created by managers and then shared with many client accounts.\n\nThe resource names of objects like these will differ, depending on which\naccount you're sending an API call to.\n\n### Example: Cross-account conversion actions\n\nAssume we have manager account `987-654-3210` that shares a cross-account\nconversion action with one of its client customer accounts `123-456-7890`:\n\nMaking an API call to the manager account to, for example, update the conversion\naction's lookback window would reference the shared object using resource name:\n`customers/9876543210/conversionActions/257733534`.\n\nMaking an API call to the *client account* to opt-in to using the shared\nconversion action would reference it using resource name:\n`customers/1234567890/conversionActions/257733534`.\n\nThis is the same underlying conversion action, but its resource name is relative\nto the account used to access it."]]
