查詢結構

資源、區隔和指標欄位的查詢可以傳送至 GoogleAdsService Search 或 SearchStream 方法。如要使用 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 子句中只能指定單一資源。在查詢中，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

重點提示： 如果 FROM 子句中的資源將另一個資源列為 segment，則選取該資源的任何屬性都會做為區隔。

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.date、segments.week、segments.month、segments.quarter 和 segments.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 可讓你截斷結果。使用 GoogleAdsService.Search 處理長長的結果清單。

參數

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。

注意： 如果您打算使用任何傳回的物件進行更新或移除作業，建議將這個選項設為 false，因為沒有資源名稱的資源無法用於變動作業。如果將這個選項設為 true，請務必明確要求主要資源和您使用查詢擷取的任何屬性資源的資源名稱。

省略未選取資源名稱的範例
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'