สร้างรายงานการค้นหาใน Search Ads 360 Reporting API

อ่านส่วนด้านล่างเพื่อดูวิธีสร้างรายงานการค้นหาใน Search Ads 360 Reporting API

บริการค้นหา

Search Ads 360 Reporting API มีบริการพิเศษสําหรับการค้นหาและการรายงาน

SearchAds360Service เป็นบริการการดึงข้อมูลและการรายงานออบเจ็กต์แบบรวมที่มีวิธีการค้นหา 2 วิธี ได้แก่ SearchStream และ Search ระบบจะส่งการค้นหาในสตริงการค้นหาที่เขียนด้วยภาษาคําค้นหาของ Search Ads 360 คุณกําหนดการค้นหาเพื่อดำเนินการต่อไปนี้ได้

• ดึงข้อมูลแอตทริบิวต์ที่เฉพาะเจาะจงของออบเจ็กต์
• ดึงข้อมูลเมตริกประสิทธิภาพของออบเจ็กต์ตามช่วงวันที่
• จัดเรียงออบเจ็กต์ตามแอตทริบิวต์
• กรองผลลัพธ์โดยใช้เงื่อนไขที่ระบุออบเจ็กต์ที่จะแสดง
• จำกัดจำนวนออบเจ็กต์ที่แสดงผล

ทั้ง 2 วิธีจะแสดงผลแถวทั้งหมดที่ตรงกับคำค้นหา ตัวอย่างเช่น เมื่อคุณดึงข้อมูล campaign.id, campaign.name และ metrics.clicks API จะแสดงผล SearchAds360Row ที่มีออบเจ็กต์แคมเปญที่มีการตั้งค่าช่อง id และ name และออบเจ็กต์ metrics ที่มีการตั้งค่าช่อง clicks

วิธีการค้นหา

SearchStream

ส่งคําขอเดียวและเริ่มการเชื่อมต่อแบบถาวรกับ Search Ads 360 Reporting API โดยไม่คํานึงถึงขนาดรายงาน

• ระบบจะเริ่มดาวน์โหลดแพ็กเก็ตข้อมูลทันทีโดยแคชผลลัพธ์ทั้งหมดไว้ในบัฟเฟอร์ข้อมูล
• โค้ดของคุณจะเริ่มอ่านข้อมูลที่บัฟเฟอร์ไว้ได้โดยไม่ต้องรอให้สตรีมทั้งรายการเล่นจบ

Search

ส่งคําขอแบบแบ่งหน้าหลายรายการเพื่อดาวน์โหลดรายงานทั้งฉบับ

SearchStream มักจะมีประสิทธิภาพดีกว่าเนื่องจากจะช่วยลดเวลาในการรับส่งข้อมูลในเครือข่ายที่จําเป็นในการขอแต่ละหน้า เราขอแนะนำให้ใช้ SearchStream สำหรับรายงานทั้งหมดที่มีมากกว่า 10,000 แถว ประสิทธิภาพของวิธีการต่างๆ สําหรับรายงานขนาดเล็ก (<10,000 แถว) นั้นไม่มีความแตกต่างกันมากนัก

วิธีการที่คุณใช้จะไม่ส่งผลต่อโควต้าและขีดจํากัดของ API: การค้นหาหรือรายงานรายการเดียวจะนับเป็นการดำเนินการ 1 ครั้ง ไม่ว่าผลลัพธ์จะแสดงเป็นหน้าเว็บหรือสตรีมก็ตาม

ตัวอย่างคำค้นหา

คําค้นหาตัวอย่างนี้จะแสดงข้อมูลประสิทธิภาพของบัญชีในช่วง 30 วันที่ผ่านมาโดยแบ่งตามแคมเปญและแยกตามอุปกรณ์

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

หมายเหตุ: ภาษาคําค้นหาของ Search Ads 360 มีรายละเอียดเกี่ยวกับวิธีใช้ประโยคแต่ละประโยคของคําค้นหา

ส่งคำขอ

หากต้องการส่งคำขอ คุณต้องส่งสตริง customer_id และ query ไปยังอินเทอร์เฟซ SearchAds360Service.SearchStream หรือ SearchAds360Service.Search

หมายเหตุ: ตัวอย่างด้านล่างแสดงคําขอ HTTP/JSON พื้นฐาน ข้อมูลนี้ใช้เพื่อสาธิตแนวคิด เราขอแนะนำให้คุณใช้ไลบรารีไคลเอ็นต์ของเราซึ่งอิงตาม gRPC เพื่อส่งคำขอในแอปของคุณเอง

คําขอประกอบด้วย HTTP POST ไปยังเซิร์ฟเวอร์ Search Ads 360 Reporting API ที่ URL ใด URL หนึ่งต่อไปนี้

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream

https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:search

ตัวอย่างที่สมบูรณ์ของคําจํากัดความรายงานที่จะ searchStream อยู่ภายในคําขอ HTTP POST มีดังนี้

POST /VERSION_NUMBER/customers/CUSTOMER_ID/searchads360:searchStream HTTP/1.1
Host: searchads360.googleapis.com
User-Agent: curl
Content-Type: application/json
Accept: application/json
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]

Parameters:
{
  "query" : "SELECT campaign.name, campaign.status, segments.device,
                    metrics.impressions, metrics.clicks, metrics.ctr,
                    metrics.average_cpc, metrics.cost_micros
            FROM campaign
            WHERE segments.date DURING LAST_30_DAYS"
}

ประมวลผลการตอบกลับ

SearchAds360Service แสดงรายการออบเจ็กต์ SearchAds360Row

SearchAds360Row แต่ละรายการแสดงถึงออบเจ็กต์ที่การค้นหาแสดงผล ออบเจ็กต์แต่ละรายการประกอบด้วยชุดแอตทริบิวต์ที่สร้างขึ้นตามช่องที่ขอในประโยค SELECT ของคําค้นหา ระบบจะไม่ป้อนข้อมูลแอตทริบิวต์ที่ไม่ได้รวมอยู่ในประโยค SELECT ลงในออบเจ็กต์ของคำตอบ

ตัวอย่างเช่น คําค้นหาด้านล่างจะป้อนข้อมูลออบเจ็กต์ SearchAds360Row แต่ละรายการด้วย campaign.id, campaign.name และ campaign.status เท่านั้น ระบบจะละเว้นแอตทริบิวต์อื่นๆ เช่น campaign.engine_id หรือ campaign.bidding_strategy_type

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign

เอกสารประกอบอ้างอิง

ส่วนข้อมูลอ้างอิงจะประกอบด้วยข้อมูลทั้งหมดที่คุณต้องใช้ในการใช้อาร์ติแฟกต์แต่ละรายการอย่างถูกต้อง แต่ละแหล่งข้อมูลจะมีหน้าเว็บ 1 หน้า เช่น ad_group และ campaign หน้า segments และ metrics จะแสดงรายการกลุ่มและช่องเมตริกที่ใช้ได้ทั้งหมด

ทรัพยากร กลุ่ม และเมตริกบางรายการใช้ร่วมกันไม่ได้ ขณะที่บางรายการใช้ร่วมกันได้และเสริมซึ่งกันและกัน หน้าแหล่งข้อมูลแต่ละหน้าจะมีข้อมูลต่อไปนี้ (หากมีและเหมาะสม) และอื่นๆ

แหล่งข้อมูลที่ระบุแหล่งที่มา

สำหรับทรัพยากรบางรายการ คุณอาจมีตัวเลือกในการรวมทรัพยากรที่เกี่ยวข้องโดยนัยโดยเลือกฟิลด์ของทรัพยากรนั้นๆ ร่วมกับฟิลด์ของทรัพยากรในประโยค FROM เช่น ทรัพยากร campaign เป็นทรัพยากรที่มีการระบุแหล่งที่มาของทรัพยากร ad_group ซึ่งหมายความว่าคุณสามารถรวมช่องต่างๆ เช่น campaign.id และ campaign.bidding_strategy_type ไว้ในข้อความค้นหาได้เมื่อใช้ ad_group ในประโยค FROM

ส่วนทรัพยากรที่มีการระบุแหล่งที่มาจะแสดงรายการทรัพยากรที่มีการระบุแหล่งที่มา ทรัพยากรบางรายการไม่มีแหล่งที่มา

คอลัมน์ฟิลด์ทรัพยากร

ช่องทั้งหมดของทรัพยากรจะรวมอยู่ในคอลัมน์ช่องทรัพยากร ช่องทรัพยากรแต่ละช่องจะลิงก์ไปยังรายละเอียดเพิ่มเติมเกี่ยวกับช่องนั้นๆ ซึ่งรวมถึงคำอธิบาย หมวดหมู่ ประเภทข้อมูล URL ประเภท และการตั้งค่าที่กรองได้ เลือกได้ จัดเรียงได้ และซ้ำได้

คอลัมน์กลุ่ม

ฟิลด์กลุ่มบางฟิลด์อาจเลือกไม่ได้กับทรัพยากรหนึ่งๆ

คอลัมน์กลุ่มจะแสดงรายการช่อง segments ที่คุณใช้ในอนุประโยค SELECT เดียวกันกับช่องของทรัพยากรได้ แต่ละช่องจะลิงก์ไปยังรายละเอียดทั้งหมดเกี่ยวกับช่องนั้นๆ ซึ่งรวมถึงคำอธิบาย หมวดหมู่ ประเภทข้อมูล ประเภท URL และการตั้งค่าที่กรองได้ เลือกได้ จัดเรียงได้ และซ้ำได้ หากคุณใช้ทรัพยากรในประโยค FROM ให้ใช้เมนูแบบเลื่อนลงใช่/ไม่ใช่เพื่อกรองกลุ่มที่ไม่มีให้ใช้ออก

คอลัมน์เมตริก

ฟิลด์เมตริกบางฟิลด์อาจเลือกไม่ได้กับทรัพยากรหนึ่งๆ

คอลัมน์เมตริกจะแสดงรายการช่อง metrics ที่คุณใช้ในเงื่อไข SELECT เดียวกันกับช่องของแหล่งข้อมูลได้ แต่ละช่องจะลิงก์ไปยังรายละเอียดทั้งหมดเกี่ยวกับช่องนั้นๆ ซึ่งรวมถึงคําอธิบาย หมวดหมู่ ประเภทข้อมูล ประเภท URL และการตั้งค่าที่กรองได้ เลือกได้ จัดเรียงได้ และซ้ำได้ หากคุณใช้ทรัพยากรในประโยค FROM ให้ใช้เมนูแบบเลื่อนลงใช่/ไม่เพื่อกรองเมตริกที่ไม่พร้อมใช้งาน

หมายเหตุ: เมื่อรับเมตริกที่เกี่ยวข้องกับสกุลเงิน (เช่น cost_micros) สำหรับวันที่ที่เจาะจงหรือช่วงวันที่ อย่าลืมใส่ segments.date ในคำสั่ง SELECT

การแบ่งกลุ่มทรัพยากร

ทรัพยากรบางรายการมีฟิลด์ทรัพยากรการแบ่งกลุ่มที่คุณเลือกได้เมื่อทรัพยากรอยู่ในประโยค FROM เช่น หากเลือกช่องแหล่งข้อมูล campaign เช่น campaign.name เมื่อใช้ campaign_budget ในประโยค FROM ระบบจะแสดงผลและแบ่งกลุ่ม campaign.resource_name โดยอัตโนมัติ เนื่องจาก campaign เป็นทรัพยากรการแบ่งกลุ่มของ campaign_budget

ส่วนทรัพยากรการแบ่งกลุ่มจะแสดงทรัพยากรการแบ่งกลุ่มที่ใช้ได้ ทรัพยากรบางรายการไม่มีทรัพยากรการแบ่งกลุ่ม

เลือกได้ด้วย

ช่อง segments บางช่องใช้ร่วมกับแหล่งข้อมูล กลุ่ม และเมตริกอื่นๆ ไม่ได้

หน้า segments จะมีช่องที่เลือกได้ซึ่งขยายได้สําหรับช่อง segments แต่ละช่อง ซึ่งจะแสดงรายการช่องทรัพยากร metrics และช่อง segments อื่นๆ ที่เข้ากันได้ทั้งหมดซึ่งคุณสามารถใส่ไว้ในประโยค SELECT

หมายเหตุ: ดูภาษาคําค้นหาของ Search Ads 360 เพื่อดูวิธีใช้ประโยคแต่ละประโยคของคําค้นหา

การแบ่งกลุ่ม

คุณแบ่งกลุ่มผลการค้นหาได้โดยเพิ่มช่อง segments.FIELD_NAME ลงในประโยค SELECT ของข้อความค้นหา

เช่น segments.device ในข้อความค้นหาด้านล่างจะแสดงรายงานที่มีแถวสำหรับ impressions ของอุปกรณ์แต่ละเครื่องสำหรับทรัพยากรที่ระบุไว้ในประโยค FROM

SELECT
  campaign.name,
  campaign.status,
  segments.device,
  metrics.impressions
FROM campaign

ผลลัพธ์ที่ SearchAds360Service.SearchStream แสดงจะมีลักษณะคล้ายกับสตริง JSON นี้

{
  "results":[
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"10922"
      },
      "segments":{
        "device":"MOBILE"
      }
    },
    {
      "campaign":{
        "resourceName":"customers/1234567890/campaigns/111111111",
        "name":"Test campaign",
        "status":"ENABLED"
      },
      "metrics":{
        "impressions":"28297"
      },
      "segments":{
        "device":"DESKTOP"
      }
    },
    ...
  ]
}

ดูรายการช่องกลุ่มที่ใช้ได้ได้ที่ segments

หลายกลุ่ม

ข้อควรระวัง: จำนวนแถวอาจเพิ่มขึ้นแบบทวีคูณสำหรับแต่ละช่องsegmentsเพิ่มเติมที่คุณเพิ่มลงในข้อความค้นหา

คุณสามารถระบุกลุ่มหลายกลุ่มในประโยค SELECT ของข้อความค้นหาได้ การตอบกลับประกอบด้วยออบเจ็กต์ SearchAds360Row 1 รายการสําหรับชุดค่าผสมของอินสแตนซ์ของทรัพยากรหลักที่ระบุไว้ในประโยค FROM และค่าของช่อง segment แต่ละช่องที่เลือก

เช่น การค้นหาต่อไปนี้จะแสดงผล 1 แถวสําหรับชุดค่าผสมของ campaign, segments.ad_network_type และ segments.date แต่ละชุด

SELECT
  segments.ad_network_type
  segments.date
FROM campaign

โปรดทราบว่าระบบจะแบ่งกลุ่มผลลัพธ์โดยนัยตามอินสแตนซ์ของแหล่งข้อมูลหลักแต่ละรายการ แต่จะไม่แบ่งตามค่าของช่องที่เลือกแต่ละช่อง

ตัวอย่างการค้นหาต่อไปนี้จะแสดงผลลัพธ์ 1 แถวต่อแคมเปญ ไม่ใช่ 1 แถวต่อค่าที่แตกต่างกันของช่อง campaign.status

SELECT
  campaign.status,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_14_DAYS

การแบ่งกลุ่มแบบไม่ระบุ

รายงานทุกฉบับจะแบ่งกลุ่มตามทรัพยากรที่ระบุไว้ในFROM ประโยค เมตริกจะแบ่งตามช่อง resource_name ของทรัพยากรนี้

หมายเหตุ: ระบบจะแสดงผลช่อง resource_name ของทรัพยากรในประโยค FROM เสมอ แม้ว่าจะไม่ได้ระบุไว้ในประโยค SELECT ก็ตาม ดูข้อมูลเพิ่มเติมในช่อง resource_name

ตัวอย่างการค้นหานี้จะแสดงผล ad_group.resource_name โดยอัตโนมัติและใช้ ad_group.resource_name เพื่อแบ่งกลุ่มเมตริกที่ระดับ ad_group โดยนัย

SELECT metrics.impressions
FROM ad_group

สตริง JSON ที่แสดงผลจะมีลักษณะคล้ายกับตัวอย่างต่อไปนี้

{
  "results":[
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/2222222222"
      },
      "metrics":{
        "impressions":"237"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/33333333333"
      },
      "metrics":{
        "impressions":"15"
      }
    },
    {
      "adGroup":{
        "resourceName":"customers/1234567890/adGroups/44444444444"
      },
      "metrics":{
        "impressions":"0"
      }
    }
  ]
}

กลุ่มวันที่หลัก

คุณสามารถใช้กลุ่มวันที่หลักในประโยคเงื่อนไข WHERE เพื่อระบุวันที่หรือระยะเวลาได้

ช่องกลุ่มต่อไปนี้เรียกว่ากลุ่มวันที่หลัก segments.date, segments.week, segments.month, segments.quarter และ segments.year

คําค้นหาตัวอย่างนี้จะแสดงเมตริก clicks ของแคมเปญในช่วง 30 วันที่ผ่านมา

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

ช่องกลุ่มวันที่หลักเป็นข้อยกเว้นจากกฎทั่วไปที่คุณใช้ช่องกลุ่มในประโยค WHERE ไม่ได้ เว้นแต่คุณจะรวมช่องดังกล่าวไว้ในประโยค SELECT ด้วย ดูข้อมูลเพิ่มเติมได้ในการกรองที่ไม่ได้รับอนุญาต

กฎกลุ่มเป้าหมายตามวันที่หลัก

• คุณสามารถใช้ช่องวันที่หลักในประโยค WHERE โดยไม่ต้องใส่ไว้ในประโยค SELECT คุณยังใส่ช่องในทั้ง 2 ประโยคได้ด้วยหากต้องการ

  การค้นหาตัวอย่างนี้จะแสดงเมตริก clicks ตามชื่อแคมเปญในช่วงวันที่ โปรดทราบว่า segments.date ไม่ได้รวมอยู่ในประโยค SELECT

  SELECT
      campaign.name,
      metrics.clicks
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

• หากรวมช่องวันที่หลักไว้ในประโยค SELECT คุณต้องระบุวันที่หรือช่วงวันที่ที่แน่นอนในประโยค WHERE ช่องที่ระบุในเงื่อไข SELECT และ WHERE ไม่จำเป็นต้องตรงกัน

  การค้นหาตัวอย่างนี้จะแสดงเมตริก clicks ตามชื่อแคมเปญที่แบ่งตามเดือนสําหรับทุกวันในช่วงวันที่

  SELECT
    campaign.name,
    metrics.clicks,
    segments.month
  FROM campaign
  WHERE segments.date > '2022-02-01'
    AND segments.date < '2022-03-01'
  

วันที่ในรูปแบบ ISO 8601

คุณสามารถใช้รูปแบบ YYYY-MM-DD (ISO 8601) เพื่อระบุวันที่และช่วงวันที่ได้ ดังนี้

WHERE segments.date BETWEEN '2022-06-01' AND '2022-06-30'

WHERE segments.date >= '2022-06-01' AND segments.date <= '2022-06-30'

สําหรับกลุ่มวันที่หลักที่ต้องใช้ระยะเวลา (segments.week, segments.month, segments.quarter) คุณสามารถใช้โอเปอเรเตอร์ = กับวันแรกของระยะเวลา ดังนี้

WHERE segments.month = '2022-06-01'

หมายเหตุ: หากระบุวันที่ที่ไม่ใช่วันแรกของระยะเวลา คุณจะได้รับข้อผิดพลาด MISALIGNED_DATE_FOR_FILTER

วันที่ที่กําหนดไว้ล่วงหน้า

นอกจากนี้ คุณยังใช้วันที่และช่วงวันที่ที่กําหนดไว้ล่วงหน้าต่อไปนี้ได้ด้วย

วันที่ที่กําหนดไว้ล่วงหน้า
TODAY	วันนี้เท่านั้น
YESTERDAY	เมื่อวานเท่านั้น
LAST_7_DAYS	7 วันก่อนหน้าโดยไม่รวมวันนี้
LAST_BUSINESS_WEEK	สัปดาห์ทำการ 5 วันก่อนหน้า (วันจันทร์ถึงศุกร์)
THIS_MONTH	ทุกวันของเดือนปัจจุบัน
LAST_MONTH	ทุกวันของเดือนก่อนหน้า
LAST_14_DAYS	14 วันที่ผ่านมา ไม่รวมวันนี้
LAST_30_DAYS	30 วันก่อนหน้าโดยไม่รวมวันนี้
THIS_WEEK_SUN_TODAY	ระยะเวลาระหว่างวันอาทิตย์ก่อนหน้ากับปัจจุบัน
THIS_WEEK_MON_TODAY	ระยะเวลาระหว่างวันจันทร์ก่อนหน้ากับวันปัจจุบัน
LAST_WEEK_SUN_SAT	ระยะเวลา 7 วันนับจากวันอาทิตย์ก่อนหน้า
LAST_WEEK_MON_SUN	ระยะเวลา 7 วันโดยเริ่มตั้งแต่วันจันทร์ก่อนหน้า

ตัวอย่าง

WHERE segments.date DURING LAST_30_DAYS

เมตริกเป็น 0

เมื่อเรียกใช้การค้นหา คุณอาจเห็นเมตริกที่มีค่าเป็น 0 สําหรับเอนทิตีบางรายการ ดูวิธีจัดการเมตริกเป็น 0 ในการค้นหา

ประเภท enum ที่ไม่รู้จัก

หากระบบแสดงผลทรัพยากรที่มีประเภทข้อมูล UNKNOWN enum แสดงว่าเวอร์ชัน API ไม่รองรับประเภทดังกล่าวอย่างเต็มรูปแบบ ทรัพยากรเหล่านี้อาจสร้างขึ้นผ่านอินเทอร์เฟซอื่นๆ เช่น มีการเปิดตัวแคมเปญหรือโฆษณาใหม่ใน UI ของ Search Ads 360 แต่ API เวอร์ชันที่คุณค้นหายังไม่รองรับ

คุณยังคงเลือกเมตริกได้เมื่อทรัพยากรมีประเภท UNKNOWN แต่ต้องคำนึงถึงสิ่งต่อไปนี้

• ระบบอาจรองรับทรัพยากรประเภท UNKNOWN ในภายหลัง แต่ทรัพยากรดังกล่าวอาจยังคงเป็น UNKNOWN ต่อไปอย่างไม่มีกำหนด
• วัตถุใหม่ที่มีประเภท UNKNOWN อาจปรากฏขึ้นได้ทุกเมื่อ ออบเจ็กต์เหล่านี้เข้ากันได้กับเวอร์ชันเก่าเนื่องจากมีค่า enum อยู่แล้ว เราจะเปิดตัวแหล่งข้อมูลเกี่ยวกับการเปลี่ยนแปลงนี้เมื่อพร้อมใช้งาน เพื่อให้คุณเห็นภาพรวมที่ถูกต้องของบัญชี ทรัพยากร UNKNOWN อาจปรากฏขึ้นเนื่องจากมีกิจกรรมใหม่ในบัญชีผ่านอินเทอร์เฟซอื่นๆ หรือเนื่องจากระบบไม่รองรับทรัพยากรอย่างเป็นทางการอีกต่อไป
• UNKNOWN ทรัพยากรอาจมีเมตริกโดยละเอียดที่แนบมาซึ่งคุณค้นหาได้
• โดยทั่วไป UNKNOWN ทรัพยากรจะปรากฏใน UI ของ Search Ads 360 อย่างเต็มรูปแบบ