تنبيه: يتم عرض مستندات واجهة REST API. تستخدم معظم مكتبات العملاء الرسمية خدمة gRPC. يمكنك الاطلاع على
مقدمة عن REST للحصول على التفاصيل.
تعيينات JSON
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
عند استخدام واجهة REST الخاصة بواجهة Google Ads API، ستتعامل مع تمثيلات JSON للموارد والأنواع نفسها المحدّدة في ملفات وصف.proto الخاصة بواجهة Google Ads API. يتّبع نظام ترميز JSON نظام الترميز الأساسي الموضّح في قسم ربط JSON ضمن دليل اللغة الخاص ببروتوكول المخازن المؤقتة.
بشكل عام، جميع الرسائل من المستوى الأعلى التي يتم إرسالها إلى الخدمات واستلامها منها هي عبارة عن كائنات JSON فردية.
تحتوي معظم طلبات التعديل على مصفوفة operations تتضمّن بدورها العديد من عمليات create أو update أو delete. وبالمثل، تكون استجابات search عبارة عن كائنات JSON تحتوي على مصفوفة results تتضمّن مجموعة نتائج طلب البحث.
يتم تحويل المعرّفات من snake_case (في آليات سلسلة البيانات المنظَّمة) إلى lowerCamelCase في JSON. أحد التحذيرات الجديرة بالذكر بشأن هذه القاعدة هو عند استخدام search أو searchStream لإرسال طلبات بحث بلغة طلب البحث في "إعلانات Google". تستخدم لغة طلب البحث نفسها تنسيق snake case، بغض النظر عن الواجهة التي تستخدمها. ومع ذلك، يتم عرض نتائج طلب البحث في REST كعناصر JSON عادية، وتكون المعرّفات الخاصة بها بتنسيق lowerCamelCase.
على سبيل المثال، يستخدم طلب البحث الذي يهدف إلى جلب قائمة بالكلمات الرئيسية النشطة في حساب ما تنسيق snake case داخل طلب البحث نفسه (ad_group_criterion، وليس adGroupCriterion):
POST /v21/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
{
"query": "SELECT ad_group_criterion.keyword.text
FROM ad_group_criterion
WHERE ad_group_criterion.type = 'KEYWORD'
AND ad_group_criterion.status = 'ENABLED'"
}
ومع ذلك، فإنّ الردّ هو تمثيل JSON للعناصر (مغلّف في مصفوفة JSON لأنّ هذا الطلب يستخدم searchStream) ويستخدم المعرّف camelCase
adGroupCriterion بدلاً من ذلك:
[
{
"results": [
{
"adGroupCriterion": {
"resourceName": "customers/1842689525/adGroupCriteria/55771861891~10003060",
"keyword": {
"text": "pay per click"
}
}
},
...
]
}
]
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Google Ads API's REST interface uses JSON to represent resources and types, following the protocol buffers' JSON encoding scheme.\u003c/p\u003e\n"],["\u003cp\u003eTop-level messages in the REST interface are JSON objects, with mutate requests typically containing an \u003ccode\u003eoperations\u003c/code\u003e array and search responses containing a \u003ccode\u003eresults\u003c/code\u003e array.\u003c/p\u003e\n"],["\u003cp\u003eIdentifiers are generally transformed from \u003cem\u003esnake_case\u003c/em\u003e to \u003cem\u003elowerCamelCase\u003c/em\u003e in JSON, with the exception of Google Ads Query Language queries, which use snake case.\u003c/p\u003e\n"],["\u003cp\u003eWhile Google Ads Query Language queries use snake case, the results returned through the REST interface utilize \u003cem\u003elowerCamelCase\u003c/em\u003e for identifiers within the JSON response objects.\u003c/p\u003e\n"]]],[],null,["# JSON Mappings\n\nWhen using the Google Ads API's REST interface, you're working with JSON\nrepresentations of the same resources and types defined in the Google Ads API's\n[.proto descriptor](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads) files. The JSON encoding scheme follows the\ncanonical encoding scheme described in the\n[JSON Mapping](/protocol-buffers/docs/proto3#json) section of the protocol\nbuffers *Language Guide*.\n\nIn general, all top-level messages to and from\n[services](https://github.com/googleapis/googleapis/tree/master/google/ads/googleads/v21/services) are single JSON objects.\nMost mutate requests contain an `operations` array that itself contains many\n`create`, `update`, or `delete` operations. Similarly, `search` responses are\nJSON objects containing a `results` array with your query's result set.\n\nIdentifiers are transformed from *snake_case* (in protocol buffers) to\n*lowerCamelCase* in JSON. One notable caveat to this rule is when using\n`search` or `searchStream` to send [Google Ads Query Language](/google-ads/api/docs/query/overview)\nqueries. The query language itself uses snake case, regardless of which\ninterface you're using. However, the results of a query in REST are returned as\nnormal JSON objects and have their identifiers in lowerCamelCase.\n\nFor example, a query to fetch a list of active keywords in an account uses\nsnake case inside the query itself (`ad_group_criterion`, not `adGroupCriterion`): \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:searchStream HTTP/1.1\nHost: googleads.googleapis.com\nContent-Type: application/json\nAuthorization: Bearer \u003cvar translate=\"no\"\u003eACCESS_TOKEN\u003c/var\u003e\ndeveloper-token: DEVELOPER_TOKEN\n\n{\n \"query\": \"SELECT ad_group_criterion.keyword.text\n FROM ad_group_criterion\n WHERE ad_group_criterion.type = 'KEYWORD'\n AND ad_group_criterion.status = 'ENABLED'\"\n}\n```\n\nHowever, the response is a JSON representation of the objects (wrapped in a JSON\narray since this request uses `searchStream`) and uses the camelCase identifier\n`adGroupCriterion` instead: \n\n```javascript\n[\n {\n \"results\": [\n {\n \"adGroupCriterion\": {\n \"resourceName\": \"customers/1842689525/adGroupCriteria/55771861891~10003060\",\n \"keyword\": {\n \"text\": \"pay per click\"\n }\n }\n },\n ...\n ]\n }\n]\n```"]]
