查詢結構

資源、區隔和指標欄位的查詢可以傳送至 GoogleAdsService SearchSearchStream 方法。如要使用 Google Ads 查詢語言建構查詢,您需要使用語言文法建構查詢。查詢由多個子句組成:

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

子句會使用欄位名稱資源名稱運算子條件排序,協助您選取正確的資料。合併為單一查詢後,即可使用 Google Ads API 發出要求。

子句

影片: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 子句中只能指定單一資源。在查詢中,FROM 子句是 Search 或 SearchStream 方法的GoogleAdsService。不過,使用 GoogleAdsFieldService 時,FROM 子句不得指定。

雖然特定查詢的 FROM 子句中只能存在一項資源,但歸因資源的欄位也可能適用。這些資源會與 FROM 子句中的資源隱含聯結,因此您只需將這些資源的屬性新增至 SELECT 子句,即可傳回這些資源的值。並非所有資源都有歸因資源。在下列範例中,您可以從廣告群組要求廣告群組 ID 和廣告活動 ID:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

系統一律會傳回主要資源的 resource_name 欄位。 在下列範例中,即使查詢中未明確選取 ad_group.resource_name,回應仍會包含這項屬性:

SELECT ad_group.id
FROM ad_group

如果選取至少一個欄位,其他資源也會套用相同做法。 舉例來說,下列查詢的回應會包含 campaign.resource_name

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

WHERE 子句會指定篩選要求資料時要套用的條件。使用 WHERE 子句時,可以指定一或多個條件,並使用 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.datesegments.weeksegments.monthsegments.quartersegments.year。如果選取任何這類區隔,則至少須在 WHERE 子句中使用其中一個區隔。

篩選時,請務必留意運算子是否區分大小寫。詳情請參閱大小寫區分

如需完整的運算子清單,請參閱語言文法

ORDER BY

ORDER BY 子句會指定傳回結果的順序。這樣一來,您就能依據欄位名稱,以遞增或遞減順序排列資料。每個排序都會指定為 field_name,後面接著 ASCDESC。如未指定 ASCDESC,則預設順序為 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

參數

PARAMETERS 子句可讓您指定要求的 meta 參數。這些參數可能會影響傳回的資料列類型。

系統支援下列中繼參數:

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

省略未選取資源名稱的範例
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_namecustomer.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_nameSELECT 子句要求的一部分。

其他語言規則

除了每個子句的範例,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'