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

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

ค้นหาบริการ

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 ของ Google

คำขอประกอบด้วย HTTP POST ที่ส่งไปยัง Search Ads 360 Reporting API เซิร์ฟเวอร์ที่ 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 มีช่อง Selectable with ที่ขยายได้สำหรับช่อง 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 ส่งคืนมาดูเหมือนจะเป็นอย่างอื่น ดังนี้

{
  "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 และ value ของช่อง 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'

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

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

วันที่ที่กำหนดไว้ล่วงหน้า
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 ในคำค้นหา

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

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

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

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