تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
التدرّج الهرمي للأسماء
إنّ أسماء الموارد المستخدَمة في Google Ads API هي أسماء هرمية، وتعكس تنظيم الكيانات ضمن "إعلانات Google". معظم الموارد هي موارد فرعية من المورد Customer، ما يشير إلى أنّه يجب أن يستهدف كل طلب بيانات من واجهة برمجة التطبيقات حسابًا معيّنًا على "إعلانات Google". على سبيل المثال، الحملات والمجموعات الإعلانية والإعلانات والكلمات الرئيسية هي جميعها موارد فرعية لمورد العميل الأساسي.
يُشار إلى عناصر "إعلانات Google" (العملاء والحملات وما إلى ذلك) بأسماء الموارد الخاصة بها في جميع أنحاء واجهة برمجة التطبيقات. ومع ذلك، من المهم ملاحظة أنّ أسماء الموارد نفسها قد تتضمّن معرّفات موارد رقمية فريدة تحدّد كل عنصر في التسلسل الهرمي. في هذه الحالات، قد يكون من المفيد تحليل اسم المورد لاستخراج معرّفات الموارد هذه وتجميع معرّف جديد.
على سبيل المثال، افحص اسم المورد AdGroupAd من الجدول السابق:
يمكن تقسيم ذلك إلى أرقام تعريف الموارد الفردية (مفصولة بأرقام تعريف المجموعة) على النحو التالي:
مكوّنات اسم المرجع
معرّفات الموارد
رقم تعريف العميل:
"1234567890"
رقم تعريف المجموعة الإعلانية:
"54321098765"
رقم تعريف الإعلان في المجموعة الإعلانية:
"2109876543210"
معرّفات المجموعات
"customers"
"adGroupAds"
يتيح لك تحليل أرقام التعريف الفردية استخلاص أسماء موارد جديدة للإشارة إلى عميل إعلان المجموعة الإعلانية (customers/1234567890) أو مجموعته الإعلانية (customers/1234567890/adGroupAds/54321098765).
معرّفات العناصر المشترَكة
ترتبط معظم العناصر في واجهة برمجة التطبيقات بعميل واحد محدّد في "إعلانات Google". ومع ذلك، هناك بعض أنواع العناصر التي يمكن مشاركتها بين حسابات متعددة. في الواقع، تشمل هذه العناصر قوائم الكلمات الرئيسية السلبية أو إجراءات الإحالات الناجحة على مستوى حسابات متعدّدة التي ينشئها عادةً المديرون ثم يشاركونها مع العديد من حسابات العملاء.
ستختلف أسماء موارد العناصر المشابهة، وذلك حسب الحساب الذي ترسل إليه طلب بيانات من واجهة برمجة التطبيقات.
مثال: إجراءات الإحالات الناجحة المُدارة في عدّة حسابات
لنفترض أنّ لدينا حسابًا إداريًا 987-654-3210 يشارك إجراء إحالة ناجحة على مستوى حسابات متعدّدة مع أحد حسابات العملاء 123-456-7890:
عند إجراء طلب بيانات من واجهة برمجة التطبيقات إلى الحساب الإداري، مثلاً لتعديل فترة البحث السابقة لإجراء الإحالة الناجحة، سيشير الطلب إلى العنصر المشترَك باستخدام اسم المورد:
customers/9876543210/conversionActions/257733534.
عند إجراء طلب إلى واجهة برمجة التطبيقات لحساب العميل من أجل الموافقة على استخدام إجراء الإحالة الناجحة المشترك، سيتم الرجوع إليه باستخدام اسم المورد:
customers/1234567890/conversionActions/257733534.
وهو إجراء الإحالة الناجحة الأساسي نفسه، ولكن اسم المورد الخاص به يكون مرتبطًا بالحساب المستخدَم للوصول إليه.
تاريخ التعديل الأخير: 2025-09-05 (حسب التوقيت العالمي المتفَّق عليه)
[[["يسهُل فهم المحتوى.","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-05 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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."]]
