查詢結構

資源、區隔和指標欄位的查詢可以傳送至 GoogleAdsService 搜尋或 SearchStream 方法。如要以 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 GoogleAdsService 搜尋或 SearchStream 方法，但使用 GoogleAdsFieldService。

特定查詢的 FROM 子句中只能有 1 項資源，但欄位 來源資源也會提供這些資源 在 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

符合上述條件的所有區隔為：segment.date、segment.week、 區隔.month、segment.quarter 和區隔.year。如果其中有任何區隔 已選取一個，至少必須在 WHERE 子句中使用其中一個。

篩選時，業者需注意的區分大小寫 。詳情請參閱區分大小寫。

如需完整的運算子清單，請參閱 文法。

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 子句中指定多個欄位，並以半形逗號分隔 請參考閱讀清單，進一步瞭解 如何選擇 Kubeflow Pipelines SDK 或 TFX系統會按照查詢中指定的順序排列。 舉例來說，在這個查詢中選取廣告群組資料時，系統會將結果排序 按廣告活動名稱遞增排序，再按數量遞減排序。 曝光，再按點擊次數遞減排序：

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 子句可讓您指定要求的中繼參數。 這些參數可能會影響傳回的資料列類型。

目前支援下列中繼參數：

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。

省略_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'
上一頁
查詢文法
下一頁
日期範圍