สร้างรายงานการค้นหาใน 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

ส่งคำขอ

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

คําขอประกอบด้วย 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 ให้ใช้เมนูแบบเลื่อนลงใช่/ไม่เพื่อกรองเมตริกที่ไม่พร้อมใช้งานออก

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

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

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

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

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

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

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

คุณแบ่งกลุ่มผลการค้นหาได้โดยเพิ่มช่อง 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

หลายกลุ่ม

คุณสามารถระบุหลายกลุ่มได้ในประโยค 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 ของทรัพยากรนี้

คำค้นหาตัวอย่างนี้จะแสดงผล 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'

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

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

ตัวอย่าง

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 อย่างเต็มรูปแบบ