โครงสร้างข้อความค้นหา

คุณสามารถส่งการค้นหาสำหรับช่องทรัพยากร กลุ่ม และเมตริกไปยังเมธอด Search หรือ SearchStream ของ GoogleAdsService หากต้องการสร้างคําค้นหาในภาษาคําค้นหาของ Google Ads คุณจะต้องสร้างโดยใช้ไวยากรณ์ภาษา คําค้นหาประกอบด้วยประโยคย่อยหลายประโยค ดังนี้

• SELECT
• FROM
• WHERE
• ORDER BY
• LIMIT
• PARAMETERS

ประโยคใช้ชื่อช่อง ชื่อทรัพยากร โอเปอเรเตอร์ เงื่อนไข และการจัดลําดับเพื่อช่วยเลือกข้อมูลที่ถูกต้อง เมื่อรวมเป็นคําค้นหาเดียวแล้ว คุณจะส่งคําขอได้โดยใช้ Google Ads API

ประเด็นสําคัญ: GoogleAdsFieldService เป็นแคตตาล็อกสําหรับไคลเอ็นต์ภาษาคําค้นหาของ Google Ads ที่มีข้อมูลเมตาเกี่ยวกับช่องทรัพยากร ช่องกลุ่ม และเมตริกทั้งหมด รวมถึงความสัมพันธ์ของช่องเหล่านี้กับแต่ละช่องและความพร้อมใช้งานในแต่ละประโยคตามที่ระบุไว้ด้านล่าง ดูรายละเอียดเพิ่มเติมได้ที่เอกสารประกอบของ GoogleAdsField

ประโยค

วิดีโอ: ความเข้ากันได้ของช่อง GAQL

SELECT

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

ตัวอย่างการค้นหาด้านล่างแสดงตัวอย่างการเลือกแอตทริบิวต์สําหรับแหล่งข้อมูลหนึ่งๆ

SELECT
  campaign.id,
  campaign.name
FROM campaign

คุณขอฟิลด์ประเภทต่างๆ ในคำขอเดียวได้ เช่น

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

• ช่องทรัพยากร

  • campaign.id
  • campaign.name

• ช่องทรัพยากร

  • bidding_strategy.id
  • bidding_strategy.name

• ช่องกลุ่ม

  • segments.device
  • segments.date

• เมตริก

  • metrics.impressions
  • metrics.clicks

ระบบอาจไม่อนุญาตให้ใช้ช่องบางช่องในประโยค SELECT เนื่องจากข้อจำกัดต่อไปนี้

• การค้นหาฟิลด์ที่เลือกไม่ได้ ช่องเหล่านี้จะมีแอตทริบิวต์ข้อมูลเมตา Selectable ที่ทำเครื่องหมายเป็น false
• การเลือกแอตทริบิวต์ของฟิลด์ที่ซ้ำ ช่องเหล่านี้จะมีแอตทริบิวต์ข้อมูลเมตา isRepeated ที่ทำเครื่องหมายเป็น true
• การเลือกช่องที่ไม่พร้อมใช้งานสําหรับทรัพยากรที่ระบุในประโยค FROM คุณไม่สามารถเลือกแอตทริบิวต์ของทรัพยากรบางรายการร่วมกันได้ และจะมีเฉพาะเมตริกและกลุ่มย่อยของเมตริกและกลุ่มทั้งหมดที่ใช้ได้กับทรัพยากรในประโยค FROM
• การเลือกกลุ่มหรือเมตริกที่ใช้ร่วมกันไม่ได้ ดูข้อมูลเพิ่มเติมเกี่ยวกับเรื่องนี้ได้ที่ส่วนการแบ่งกลุ่ม

ดูข้อมูลเกี่ยวกับเงื่อนไขข้างต้นได้ในเอกสารอ้างอิงของเรา หรือจาก GoogleAdsFieldService

จาก

ประโยค FROM จะระบุทรัพยากรหลักที่จะแสดง แหล่งข้อมูลในประโยค FROM จะกำหนดช่องที่ใช้กับประโยคอื่นๆ ทั้งหมดสำหรับคำค้นหาหนึ่งๆ ได้ ระบุทรัพยากรได้เพียงรายการเดียวในอนุประโยค FROM ต้องใช้อนุประโยค FROM ในคําค้นหาเพื่อเรียกใช้เมธอด Search หรือ SearchStream ของ GoogleAdsService แต่ไม่ควรระบุเมื่อใช้ GoogleAdsFieldService

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

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

SELECT ad_group.id
FROM ad_group

เช่นเดียวกับทรัพยากรอื่นๆ เมื่อเลือกฟิลด์อย่างน้อย 1 ช่อง ตัวอย่างเช่น campaign.resource_name จะรวมอยู่ในการตอบกลับสําหรับการค้นหาต่อไปนี้

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

ประเด็นสำคัญ: หากทรัพยากรในประโยค FROM แสดงทรัพยากรอื่นเป็น segment การเลือกแอตทริบิวต์ของทรัพยากรนั้นจะเป็นกลุ่ม

ที่ไหน

ประโยค WHERE จะระบุเงื่อนไขที่จะใช้เมื่อกรองข้อมูลสําหรับคําขอ เมื่อใช้ประโยค WHERE คุณจะระบุเงื่อนไขได้อย่างน้อย 1 รายการโดยใช้ AND เพื่อแยกเงื่อนไข เงื่อนไขแต่ละรายการควรเป็นไปตามรูปแบบ field_name Operator value ประโยค WHERE เป็นประโยคที่ไม่บังคับในข้อความค้นหา

ต่อไปนี้เป็นตัวอย่างการใช้ WHERE เพื่อแสดงผลเมตริกจากระยะเวลาหนึ่งๆ

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

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

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

กลุ่มในประโยค WHERE ต้องอยู่ในประโยค SELECT โดยมีกลุ่มวันที่ต่อไปนี้ซึ่งเรียกว่ากลุ่มวันที่หลักเป็นข้อยกเว้น

• segments.date
• segments.week
• segments.month
• segments.quarter
• segments.year

ในข้อความค้นหาต่อไปนี้ โปรดสังเกตว่ามีการเลือก segments.date เนื่องจากกลุ่มนี้เป็นกลุ่มวันที่หลัก จึงต้องมีการระบุช่วงวันที่ที่สิ้นสุดซึ่งประกอบด้วยกลุ่มวันที่หลักในประโยคเงื่อนไข WHERE

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

กลุ่มทั้งหมดที่ตรงกับเงื่อนไขข้างต้น ได้แก่ segments.date, segments.week, segments.month, segments.quarter และ segments.year หากเลือกกลุ่มเหล่านี้ จะต้องใส่กลุ่มอย่างน้อย 1 กลุ่มไว้ในประโยค WHERE

ประเด็นหลัก: ตัวคั่น AND ใช้ได้ระหว่างเงื่อนไขโอเปอเรเตอร์เท่านั้น (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE") และต้องไม่ใช้ภายในเงื่อนไขโอเปอเรเตอร์เดียว (WHERE segments.device != "DESKTOP" AND "MOBILE")

เมื่อกรอง คุณควรคำนึงถึงการคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ของโอเปอเรเตอร์ ดูรายละเอียดเพิ่มเติมเกี่ยวกับการคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่

ดูรายการโอเปอเรเตอร์ทั้งหมดได้ที่ไวยากรณ์

ORDER BY

ประโยค ORDER BY จะระบุลําดับที่ระบบจะแสดงผลลัพธ์ ซึ่งจะช่วยให้คุณจัดเรียงข้อมูลตามลําดับจากน้อยไปมากหรือมากไปน้อยได้ โดยอิงตามชื่อช่อง การจัดเรียงแต่ละรายการจะระบุเป็น field_name ตามด้วย ASC หรือ DESC หากไม่ได้ระบุ ASC หรือ DESC ระบบจะใช้ ASC เป็นค่าเริ่มต้น ประโยค ORDER BY เป็นประโยคที่ไม่บังคับในข้อความค้นหา

คําค้นหาต่อไปนี้จะจัดเรียงแคมเปญที่แสดงผลตามจํานวนการคลิกจากสูงสุดไปต่ำสุด

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

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

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

LIMIT

ประโยค LIMIT ช่วยให้คุณระบุจำนวนผลลัพธ์ที่จะแสดงได้ ซึ่งจะเป็นประโยชน์ในกรณีที่คุณสนใจเฉพาะข้อมูลสรุป

เช่น คุณสามารถใช้ LIMIT เพื่อจำกัดจำนวนผลลัพธ์ทั้งหมดสําหรับการค้นหาต่อไปนี้

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

ประเด็นสำคัญ: LIMIT ช่วยให้คุณตัดผลลัพธ์ได้ ใช้ช่อง page_size ของ GoogleAdsService.Search เพื่อจัดการรายการผลลัพธ์ที่ยาว

พารามิเตอร์

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

ปัจจุบันระบบรองรับเมตาพารามิเตอร์ต่อไปนี้

include_drafts

ตั้งค่า include_drafts เป็น true เพื่ออนุญาตให้แสดงผลเอนทิตีฉบับร่าง ค่าเริ่มต้นคือ false

ตัวอย่างเช่น คําค้นหาต่อไปนี้จะดึงข้อมูลแคมเปญฉบับร่างพร้อมกับแคมเปญปกติ

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

omit_unselected_resource_names

ตั้งค่า omit_unselected_resource_names เป็น true เพื่อป้องกันไม่ให้ระบบแสดงชื่อทรัพยากรของทรัพยากรแต่ละประเภทในการตอบกลับ เว้นแต่จะมีการขออย่างชัดเจนในประโยค SELECT ค่าเริ่มต้นคือ false

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

omit_unselected_resource_names examples
SELECT campaign.name, customer.id FROM campaign	Returned resources: campaign.resource_name customer.resource_name omit_unselected_resource_names มีค่าเริ่มต้นเป็น false ดังนั้นระบบจะแสดงผลช่อง resource_name ทั้งหมด
SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resources: ไม่มี omit_unselected_resource_names ระบุเป็น true และ campaign.resource_name และ customer.resource_name ไม่ได้เป็นส่วนหนึ่งของประโยค SELECT
SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true	Returned resource: campaign.resource_name omit_unselected_resource_names ระบุเป็น true และขอ campaign.resource_name เป็นส่วนหนึ่งของข้อย่อย SELECT

กฎภาษาเพิ่มเติม

นอกจากตัวอย่างของประโยคแต่ละประโยคแล้ว ภาษาของคําค้นหาของ Google Ads ยังมีลักษณะการทํางานต่อไปนี้ที่นําไปใช้ได้

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

  SELECT campaign.id
  FROM ad_group
  WHERE ad_group.status = PAUSED
  

• คุณเลือกเมตริกสําหรับทรัพยากรหนึ่งๆ ได้โดยเฉพาะ โดยไม่จำเป็นต้องมีช่องอื่นๆ จากทรัพยากรนั้นในคําค้นหา

  SELECT
    metrics.impressions,
    metrics.clicks,
    metrics.cost_micros
  FROM campaign
  

• คุณเลือกช่องการแบ่งกลุ่มได้โดยไม่ต้องมีช่องทรัพยากรหรือเมตริกประกอบ

  SELECT segments.device FROM campaign
  

• ฟิลด์ resource_name (เช่น campaign.resource_name) สามารถใช้เพื่อกรองหรือจัดเรียงข้อมูลได้ ดังนี้

  SELECT
    campaign.id,
    campaign.name
  FROM campaign
  WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'