Search Ads 360 Reporting API เวอร์ชันใหม่พร้อมให้ใช้งานแล้ว เข้าร่วมกลุ่ม Google
searchads-api-announcements เพื่อติดตามการปรับปรุงและรุ่นที่กำลังจะเปิดตัว
โครงสร้างการรายงาน API ของ Search Ads 360
จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน
บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ
องค์ประกอบหลักของ Search Ads 360 Reporting API คือทรัพยากรและบริการ ทรัพยากรแสดงถึงเอนทิตี Search Ads 360 และคุณใช้บริการเพื่อดึงข้อมูลเอนทิตี Search Ads 360
ลําดับชั้นของออบเจ็กต์
บัญชี Search Ads 360 คือลําดับชั้นของออบเจ็กต์
ทรัพยากรระดับบนสุดของบัญชีคือลูกค้า
แต่ละบัญชีมีแคมเปญที่ใช้งานอยู่อย่างน้อย 1 รายการ
Campaign แต่ละรายการจะมีกลุ่มโฆษณาอย่างน้อย 1 กลุ่มที่จัดกลุ่มโฆษณาไว้เป็นคอลเล็กชันเชิงตรรกะ
AdGroup แต่ละรายการมีโฆษณากลุ่มโฆษณาอย่างน้อย 1 รายการ
คุณแนบ AdGroupCriterion หรือ CampaignCriterion อย่างน้อย 1 รายการลงในกลุ่มโฆษณาหรือแคมเปญได้ เกณฑ์จะกําหนดวิธีเรียกให้โฆษณาแสดง
- ประเภทเกณฑ์มีหลายประเภท เช่น คีย์เวิร์ด ช่วงอายุ และสถานที่ตั้ง เกณฑ์ที่กำหนดในระดับแคมเปญจะมีผลต่อทรัพยากรอื่นๆ ทั้งหมดภายในแคมเปญ นอกจากนี้ คุณยังระบุงบประมาณและวันที่สำหรับทั้งแคมเปญได้ด้วย
แหล่งข้อมูล
ทรัพยากรแสดงถึงเอนทิตีในบัญชี Search Ads 360 ตัวอย่างแหล่งข้อมูล ได้แก่ Customer, Campaign และ AdGroup
รหัสออบเจ็กต์
ออบเจ็กต์ทุกรายการใน Search Ads 360 จะระบุด้วยรหัสของตัวเอง รหัสบางรายการจะไม่เหมือนใครทั่วโลก ซึ่งก็คือในบัญชี Search Ads 360 ทั้งหมด ขณะที่รหัสอื่นๆ จะไม่เหมือนใครเฉพาะภายในขอบเขตที่จำกัดเท่านั้น
| ขอบเขตความไม่ซ้ำกันของรหัสออบเจ็กต์ |
| รหัสงบประมาณ |
ทั่วโลก |
| รหัสแคมเปญ |
ทั่วโลก |
| รหัส AdGroup |
ทั่วโลก |
| รหัสโฆษณา |
กลุ่มโฆษณาคู่ AdGroupId / AdId แต่ละคู่จะซ้ำกันไม่ได้ทั่วโลก |
| รหัส AdGroupCriterion |
กลุ่มโฆษณาคู่ AdGroupId / CriterionId แต่ละคู่ไม่ซ้ำกันทั่วโลก |
| รหัสเกณฑ์แคมเปญ |
แคมเปญคู่ CampaignId / CriterionId แต่ละคู่จะซ้ำกันไม่ได้ทั่วโลก |
| ส่วนขยายโฆษณา |
แคมเปญคู่ CampaignId / AdExtensionId แต่ละคู่จะซ้ำกันไม่ได้ทั่วโลก |
| รหัสฟีด |
ทั่วโลก |
| รหัสรายการฟีด |
ทั่วโลก |
| รหัสแอตทริบิวต์ฟีด |
ฟีด |
| รหัสการแมปฟีด |
ทั่วโลก |
| รหัสป้ายกำกับ |
ทั่วโลก |
| รหัส UserList |
ทั่วโลก |
กฎรหัสเหล่านี้อาจมีประโยชน์เมื่อออกแบบพื้นที่เก็บข้อมูลในเครื่องสำหรับออบเจ็กต์ Search Ads 360
ประเภทออบเจ็กต์
ออบเจ็กต์บางอย่างใช้ได้กับเอนทิตีหลายประเภท ในกรณีนี้ ออบเจ็กต์จะมีช่อง type ที่อธิบายเนื้อหา เช่น AdGroupAd อาจหมายถึงโฆษณาแบบข้อความ โฆษณาโรงแรม หรือโฆษณาในพื้นที่
คุณสามารถเข้าถึงค่าประเภทผ่านช่อง AdGroupAd.ad.type ระบบจะแสดงค่าของ AdType ใน Enum
ชื่อทรัพยากร
ทรัพยากรแต่ละรายการจะได้รับการระบุโดยไม่ซ้ำกันด้วยสตริง resource_name ที่เชื่อมต่อทรัพยากรและระดับบนสุดของทรัพยากรเข้ากับเส้นทาง
ตัวอย่างเช่น ชื่อทรัพยากรแคมเปญมีรูปแบบดังนี้
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
แคมเปญที่มีรหัส 987654 ในบัญชี Search Ads 360 ที่มีรหัสลูกค้า
1234567 มีresource_nameดังนี้
customers/1234567/campaigns/987654
บริการ
บริการช่วยให้คุณเรียกข้อมูลเอนทิตีและข้อมูลเมตาของ Search Ads 360 ได้ บริการมี 3 ประเภท ได้แก่
- บริการค้นหา
SearchAds360Service เป็นบริการแบบรวมศูนย์เพียงบริการเดียวสําหรับการเรียกข้อมูลออบเจ็กต์ทรัพยากรและสถิติประสิทธิภาพทั้งหมด ซึ่งทำได้ 2 วิธี ได้แก่ Search และ SearchStream ทั้ง 2 วิธีต้องใช้การค้นหาที่ระบุแหล่งข้อมูลที่จะค้นหา แอตทริบิวต์แหล่งข้อมูล และเมตริกประสิทธิภาพที่จะดึงข้อมูล พรอมต์ที่ใช้กรองคําขอ และกลุ่มที่จะใช้แจกแจงสถิติประสิทธิภาพเพิ่มเติม ดูข้อมูลเพิ่มเติมที่สร้างรายงานการค้นหาและภาษาการค้นหาของ Search Ads 360- บริการภาคสนาม
SearchAds360FieldService จะดึงข้อมูลเมตาเกี่ยวกับทรัพยากร เช่น แอตทริบิวต์ที่ใช้ได้สําหรับทรัพยากรและประเภทข้อมูล คุณขอแคตตาล็อกสำหรับทรัพยากร ช่องทรัพยากร คีย์การแบ่งกลุ่มลูกค้า และเมตริกที่มีอยู่ในวิธีการค้นหาของ SearchAds360Service ได้ ดูข้อมูลเพิ่มเติมที่หัวข้อเรียกข้อมูลเมตาของทรัพยากร- บริการเฉพาะสำหรับเอนทิตี
บริการเหล่านี้มีGETวิธีการส่งคําขอที่ดึงข้อมูลอินสแตนซ์ทรัพยากรรายการเดียว ซึ่งมีประโยชน์สำหรับการตรวจสอบโครงสร้างของทรัพยากร
ตัวอย่างบริการเฉพาะบุคคล ได้แก่
เนื้อหาของหน้าเว็บนี้ได้รับอนุญาตภายใต้ใบอนุญาตที่ต้องระบุที่มาของครีเอทีฟคอมมอนส์ 4.0 และตัวอย่างโค้ดได้รับอนุญาตภายใต้ใบอนุญาต Apache 2.0 เว้นแต่จะระบุไว้เป็นอย่างอื่น โปรดดูรายละเอียดที่นโยบายเว็บไซต์ Google Developers Java เป็นเครื่องหมายการค้าจดทะเบียนของ Oracle และ/หรือบริษัทในเครือ
อัปเดตล่าสุด 2025-08-29 UTC
[null,null,["อัปเดตล่าสุด 2025-08-29 UTC"],[[["\u003cp\u003eThe Search Ads 360 Reporting API uses resources to represent Search Ads 360 entities and services to retrieve them, with the core being the SearchAds360Service for comprehensive data retrieval.\u003c/p\u003e\n"],["\u003cp\u003eSearch Ads 360 accounts are structured hierarchically, starting with the customer resource at the top, followed by campaigns, ad groups, ads, and criteria for targeting.\u003c/p\u003e\n"],["\u003cp\u003eEvery Search Ads 360 object has a unique ID, some globally and others within a specific scope like an ad group or campaign, which is important for data management.\u003c/p\u003e\n"],["\u003cp\u003eResources are identified by resource names, which are strings that combine the resource and its parent resources in a path format, such as customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID.\u003c/p\u003e\n"],["\u003cp\u003eThe Search Ads 360 Reporting API provides services like SearchAds360Service for data retrieval, SearchAds360FieldService for resource metadata, and entity-specific services for detailed information on individual resources like custom columns.\u003c/p\u003e\n"]]],["The Search Ads 360 Reporting API uses resources (entities) and services (retrieval methods). Resources, like `Customer`, `Campaign`, and `AdGroup`, are organized hierarchically. Each object has a unique ID with varying scopes and a `resource_name` for identification. Services include `SearchAds360Service` to retrieve resources and statistics, `SearchAds360FieldService` for metadata, and entity-specific services for individual resource instances. `SearchAds360Service` uses queries with attributes, metrics, predicates, and segments to filter data.\n"],null,["# Search Ads 360 Reporting API structure\n\nThe primary components of the Search Ads 360 Reporting API are *resources* and\n*services*. A resource represents a Search Ads 360 entity and you use a service\nto retrieve Search Ads 360 entities.\n\nObject hierarchy\n----------------\n\nA Search Ads 360 account is a hierarchy of objects.\n\n- The top-level resource of an account is the [customer](/search-ads/reporting/api/reference/fields/v0/customer).\n\n- Each account contains one or more active [campaigns](/search-ads/reporting/api/reference/fields/v0/campaign).\n\n- Each `Campaign` contains one or more [ad groups](/search-ads/reporting/api/reference/fields/v0/ad_group) that group your ads into\n logical collections.\n\n- Each `AdGroup` contains one or more [ad group ads](/search-ads/reporting/api/reference/rpc/ad_group_ad).\n\n- You can attach one or more [`AdGroupCriterion`](/search-ads/reporting/api/reference/fields/v0/ad_group_criterion) or [`CampaignCriterion`](/search-ads/reporting/api/reference/fields/v0/campaign_criterion)\n to an ad group or campaign. Criteria define how ads are triggered.\n\n - There are many [criterion types](), such as, keywords, age ranges, and locations. Criteria defined at the campaign level affect all other resources within the campaign. You can also specify campaign-wide budgets and dates.\n\nResources\n---------\n\nResources represent the entities in your Search Ads 360 account. Example\nresources include [`Customer`](/search-ads/reporting/api/reference/fields/v0/customer), [`Campaign`](/search-ads/reporting/api/reference/fields/v0/campaign) and [`AdGroup`](/search-ads/reporting/api/reference/fields/v0/ad_group).\n\n### Object IDs\n\nEvery object in Search Ads 360 is identified by its own ID. Some IDs are\nglobally unique, that is, across all Search Ads 360 accounts, while others\nare unique only within a confined scope.\n\n| Object ID uniqueness scope ||\n|----------------------|------------------------------------------------------------------------------|\n| Budget ID | Global |\n| Campaign ID | Global |\n| AdGroup ID | Global |\n| Ad ID | Ad Group \u003cbr /\u003e Each `AdGroupId` / `AdId` pair is globally unique. |\n| AdGroupCriterion ID | Ad Group \u003cbr /\u003e Each `AdGroupId` / `CriterionId` pair is globally unique. |\n| CampaignCriterion ID | Campaign \u003cbr /\u003e Each `CampaignId` / `CriterionId` pair is globally unique. |\n| Ad Extensions | Campaign \u003cbr /\u003e Each `CampaignId` / `AdExtensionId` pair is globally unique. |\n| Feed ID | Global |\n| Feed Item ID | Global |\n| Feed Attribute ID | Feed |\n| Feed Mapping ID | Global |\n| Label ID | Global |\n| UserList ID | Global |\n\nThese ID rules can be useful when designing local storage for your Search Ads\n360 objects.\n\n### Object types\n\nSome objects can be used for multiple entity types. If this is the case, the\nobject contains a `type` field that describes its contents. For example,\n[`AdGroupAd`](/search-ads/reporting/api/reference/rpc/ad_group_ad) can refer to a text ad, hotel ad, or local ad.\nYou can access the type value through the [`AdGroupAd.ad.type`](/search-ads/reporting/api/reference/rpc/add_group_ad) field. Its\nvalue is returned in the [`AdType`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.enums#adtypeenum) enum.\n\n### Resource names\n\nEach resource is uniquely identified by a `resource_name` string that\nconcatenates the resource and its parents into a path.\n\nCampaign resource names, for example, have the form: \n\n```scdoc\ncustomers/CUSTOMER_ID/campaigns/CAMPAIGN_ID\n```\n\nA campaign with ID `987654` in the Search Ads 360 account with customer ID\n`1234567`, has the `resource_name`: \n\n```text\ncustomers/1234567/campaigns/987654\n```\n\nServices\n--------\n\nServices let you retrieve your Search Ads 360 entities and metadata. There a\nthree service types:\n\nSearch service\n: [`SearchAds360Service`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360service) is the single, unified service for retrieving all\n resource objects and performance statistics. It provides two methods: *`Search`*\n and *`SearchStream`* . Both methods require require a query that specifies the\n resource to query, the resource attributes and performance metrics to retrieve,\n the predicates to use for filtering the request, and the segments to use to\n further break down performance statistics. See [Create search reports](/search-ads/reporting/concepts/search-reports) and [Search\n Ads 360 Query Language](/search-ads/reporting/concepts/query-language) for more\n information.\n\nField service\n: [`SearchAds360FieldService`](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#searchads360fieldservice) retrieves metadata\n about resources, such as, the available attributes for a resource and its data\n type. You can request the catalog for resources, resource fields, segmentation\n keys, and metrics available in the `SearchAds360Service` search methods. See\n [Retrieve resource metadata](/search-ads/reporting/concepts/field-service)\n to learn more.\n\nEntity-specific services\n\n: These services provide a `GET` request method that retrieves a single resource\n instance. This is useful for examining the structure of a resource.\n\n Examples of entity-specific services include:\n\n - [CustomColumnService](/search-ads/reporting/api/reference/rpc/google.ads.searchads360.v0.services#customcolumnservice) that returns the requested custom column in full detail."]]
