Chú ý: Bạn đang xem tài liệu về giao diện REST của API. Hầu hết các thư viện ứng dụng chính thức của chúng tôi đều sử dụng gRPC. Hãy xem Giới thiệu về REST để biết chi tiết.
Bạn có thể tạo truy vấn bằng một trong hai phương thức Search hoặc SearchStream.
Cả hai phương thức đều hỗ trợ các truy vấn giống nhau và trả về kết quả tương đương. Phương thức Search trả về dữ liệu trong các trang có kích thước cố định gồm 10.000 hàng, cho phép bạn lặp lại một tập kết quả bằng cách sử dụng tính năng phân trang. Điều này có thể mang lại lợi thế trong điều kiện mạng có băng thông thấp hoặc không đáng tin cậy, chẳng hạn như phân đoạn một tập hợp kết quả lớn thành các phản hồi nhỏ hơn có thể được tìm nạp lại nếu mất kết nối. Mặt khác, phương thức SearchStream truyền toàn bộ tập kết quả trở lại trong một phản hồi duy nhất, có thể hiệu quả hơn cho việc truy xuất dữ liệu hàng loạt.
Cả Search và SearchStream đều sử dụng cùng một URL cơ sở:
POST/v21/customers/CUSTOMER_ID/googleAds:searchHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"}
Nếu có hơn 10.000 hàng trong kết quả,thì nextPageToken sẽ được trả về trong phản hồi:
Việc lặp lại cùng một truy vấn với pageToken được thêm vào các giá trị từ yêu cầu trước sẽ tìm nạp trang kết quả tiếp theo:
POST/v21/customers/CUSTOMER_ID/googleAds:searchHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'","pageToken":"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B"}
Để sử dụng phương thức SearchStream (trả về tất cả kết quả trong một phản hồi được truyền trực tuyến duy nhất), hãy thay đổi phương thức dịch vụ trong URL thành searchStream (pageToken không bắt buộc đối với SearchStream):
POST/v21/customers/CUSTOMER_ID/googleAds:searchStreamHTTP/1.1Host:googleads.googleapis.comContent-Type:application/jsonAuthorization:Bearer ACCESS_TOKENdeveloper-token:DEVELOPER_TOKEN{"query":"SELECT ad_group_criterion.keyword.text, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'"}
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-09-05 UTC."],[[["\u003cp\u003eThe Google Ads API offers a unified mechanism for retrieving attributes and reporting metrics, allowing you to create complex queries using the Google Ads Query Language.\u003c/p\u003e\n"],["\u003cp\u003eYou can retrieve data using either the \u003ccode\u003eSearch\u003c/code\u003e or \u003ccode\u003eSearchStream\u003c/code\u003e methods, with \u003ccode\u003eSearch\u003c/code\u003e returning paginated results and \u003ccode\u003eSearchStream\u003c/code\u003e providing a single streamed response.\u003c/p\u003e\n"],["\u003cp\u003eFor large result sets exceeding 10,000 rows, use the \u003ccode\u003enextPageToken\u003c/code\u003e to retrieve subsequent pages of data when using the \u003ccode\u003eSearch\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eBoth \u003ccode\u003eSearch\u003c/code\u003e and \u003ccode\u003eSearchStream\u003c/code\u003e utilize the same base URL and query structure, differing only in how the results are delivered.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003eSearchStream\u003c/code\u003e method wraps results in a JSON array, unlike most other API calls which return a single JSON object.\u003c/p\u003e\n"]]],[],null,["# Search & SearchStream\n\nondemand_video\n[Video: Reporting](/google-ads/api/videos/catalog/working-with-rest-3)\n| **Note:** Refer to the [reporting guide](/google-ads/api/docs/reporting/overview) to learn about various reporting concepts.\n| **Note:** See the [Search](/google-ads/api/rest/examples#search) section of the accompanying examples for more complete examples.\n\nThe Google Ads API has a unified [attribute retrieval and metrics reporting\nmechanism](/google-ads/api/docs/reporting/overview)\nthat lets you create queries using the [Google Ads Query\nLanguage](/google-ads/api/docs/query/overview).\nThis enables complex queries that can return large quantities of data about\nindividual Google Ads accounts.\n\nYou can create queries using either of the `Search` or `SearchStream` methods.\nBoth methods support the same queries and return equivalent results. The\n`Search` method returns data in fixed size pages of 10,000 rows, enabling you\nto iterate over a result set using pagination. This could be advantageous in low\nbandwidth or unreliable network conditions, for example, to segment a large\nresult set into smaller responses that can be re-fetched if a connection is\nlost. The `SearchStream` method, on the other hand, streams the entire result\nset back in a single response, which can be more efficient for bulk data\nretrieval.\n\nBoth `Search` and `SearchStream` use the same base URL: \n\n```html\n https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds\n``` \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:search 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, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'\"\n}\n```\n\nIf there are more than 10,000 rows in the results a `nextPageToken` is\nreturned in the response: \n\n```javascript\n{\n \"results\": [\n // ...\n // ...\n // ...\n ],\n \"nextPageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\",\n \"fieldMask\": \"adGroupCriterion.keyword.text,adGroupCriterion.status\"\n}\n```\n\nRepeating the same query with a `pageToken` added with the values from the\nprevious request fetches the next page of results: \n\n```http\nPOST /v21/customers/\u003cvar translate=\"no\"\u003eCUSTOMER_ID\u003c/var\u003e/googleAds:search 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, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'\",\n\"pageToken\": \"CPii5aS87vfFTBAKGJvk36qpLiIWUW5SZk8xa1JPaXJVdXdIR05JUUpxZyoCVjMwADjUBkD___________8B\"\n}\n```\n\nTo use the `SearchStream` method, which returns all results in a single streamed\nresponse, change the service method in the URL to `searchStream`\n(`pageToken` is not required by `SearchStream`): \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, ad_group_criterion.status FROM ad_group_criterion WHERE ad_group_criterion.type = 'KEYWORD' AND ad_group_criterion.status = 'ENABLED'\"\n}\n```\n| **Note:** The results of a `SearchStream` API call are wrapped in a JSON array, whereas most other API calls return a single JSON object as the response message. See the [JSON mappings](/google-ads/api/rest/design/json-mappings) section for more info."]]
