احتیاط: شما در حال مشاهده اسناد رابط 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 (در بافرهای پروتکل) به lowCamelCase در JSON تبدیل می شوند. یکی از اخطارهای قابل توجه در مورد این قانون زمانی است که search یا searchStream برای ارسال جستجوهای زبان جستجوی Google Ads استفاده می کنید. خود زبان پرس و جو از snake case استفاده می کند، صرف نظر از اینکه از کدام رابط استفاده می کنید. با این حال، نتایج یک پرس و جو در REST به عنوان اشیاء JSON معمولی برگردانده می شوند و شناسه های خود را در lowCamelCase دارند.
به عنوان مثال، یک پرس و جو برای واکشی لیستی از کلمات کلیدی فعال در یک حساب، از حروف snake در داخل خود درخواست استفاده می کند ( 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 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-26 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-26 بهوقت ساعت هماهنگ جهانی."],[[["\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```"]]
