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

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

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

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

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

ข้อกำหนด

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

เลือก

คำสั่ง 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 ในการค้นหาไปยัง GoogleAdsService ค้นหา หรือ SearchStream อย่างไรก็ตาม คุณไม่ควรระบุเมื่อใช้ GoogleAdsFieldService

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

กลุ่มทั้งหมดที่เป็นไปตามเงื่อนไขข้างต้น ได้แก่ groups.date, segments.week, segmentation.month,segment.quarter และsegment.year แล้ว หากกลุ่มใดกลุ่มหนึ่งเหล่านี้ ที่เลือกไว้ คุณต้องใช้อย่างน้อยหนึ่งรายการในวรรค 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 โปรดตรวจสอบว่าคุณได้ขอชื่อทรัพยากรของทั้ง 2 อย่างอย่างชัดแจ้ง ทรัพยากรหลักและทรัพยากรแอตทริบิวต์ที่คุณดึงข้อมูลโดยใช้การค้นหา

ตัวอย่าง omit_unselected_resource_names
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 สำหรับการค้นหา ตัวอย่างเช่น คุณอาจต้องการใช้ ฟิลด์ทรัพยากรเพื่อกรองข้อมูล:

  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'