Google Ads 查詢語言

查詢資源或中繼資料資訊

Google Ads 查詢語言可向 Google Ads API 查詢下列類型的資訊：

使用 GoogleAdsService「搜尋」或「SearchStream」查詢資源及其相關屬性、區隔和指標： GoogleAdsService 查詢的結果是 GoogleAdsRow 執行個體清單，每個 GoogleAdsRow 代表一個資源。

如果要求任何屬性或指標，資料列也會包含這些欄位。如果要求任何區隔，回應也會針對每個區隔資源元組顯示額外資料列。
GoogleAdsFieldService 中可用欄位和資源的中繼資料：這項服務提供可查詢欄位的目錄，並詳細說明這些欄位的相容性和類型。

GoogleAdsFieldService 查詢的結果是 GoogleAdsField 執行個體清單，每個 GoogleAdsField 都包含所要求欄位的詳細資料。

查詢資源屬性

以下是廣告活動資源屬性的基本查詢範例，說明如何傳回廣告活動 ID、名稱和狀態：

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

這項查詢會依廣告活動 ID 排序。每個產生的 GoogleAdsRow 都代表一個 campaign 物件，其中填入所選欄位，包括廣告活動的 resource_name。

如要瞭解廣告活動查詢可用的其他欄位，請參閱Campaign參考說明文件。

查詢指標

除了特定資源的所選屬性，您也可以查詢相關指標：

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

這項查詢會篩選出狀態為 PAUSED 且曝光次數超過 1000 的廣告活動，並依廣告活動 ID 排序。每個產生的 GoogleAdsRow 都會有 metrics 欄位，其中填入所選指標。

如需可查詢的指標清單，請參閱Metrics說明文件。

查詢區隔

除了特定資源的所選屬性，您也可以查詢相關區隔：

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date,
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date during LAST_30_DAYS
ORDER BY campaign.id

與查詢指標類似，這項查詢只會篩選狀態為 PAUSED 且曝光次數超過 1000 的廣告活動。不過，這項查詢會依日期區隔資料。這會導致每個結果 GoogleAdsRow 代表廣告活動和日期的元組 Segment。區隔會分割所選指標，並依據 SELECT 子句中的每個區隔分組。

如需可查詢的區隔清單，請參閱Segments說明文件。

查詢相關資源的屬性

在特定資源的查詢中，您或許可以加入其他相關資源 (如有)。這些相關資源稱為「已歸因資源」。在查詢中選取屬性，即可隱含地加入已歸因的資源。

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

這項查詢不僅會選取廣告活動屬性，還會從選取的每個廣告活動中擷取相關屬性。每個產生的 GoogleAdsRow 代表一個 campaign 物件，其中填入所選廣告活動屬性，以及所選出價策略屬性 bidding_strategy.name。

如要瞭解廣告活動查詢可用的歸因資源，請參閱Campaign參考說明文件。

根據查詢結果進行變動

查詢特定資源時，您可以立即將傳回的結果視為物件、修改這些物件，然後傳回該資源服務的變動方法。以下是工作流程範例： 1. 針對目前PAUSED且曝光次數超過 1000 的所有廣告活動執行查詢。 1. 從回應中每個 GoogleAdsRow 的 campaign 欄位取得 Campaign 物件。1. 將每個廣告活動的狀態從「PAUSED」變更為「ENABLED」。 1. 呼叫 CampaignService.MutateCampaigns ，並提供修改後的廣告活動來更新。

欄位中繼資料

傳送至 GoogleAdsFieldService 的查詢是用於擷取欄位中繼資料。這項資訊可協助您瞭解如何在查詢中一併使用這些欄位。由於資料可透過 API 取得，且 API 提供驗證或建構查詢所需的必要中繼資料，因此開發人員可以透過程式輔助完成這項作業。以下是中繼資料的典型查詢：

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

您可以在這項查詢中，將 <INSERT_RESOURCE_OR_FIELD> 替換為資源 (例如 customer 或 campaign) 或欄位 (例如 campaign.id、metrics.impressions 或 ad_group.id)。

如需可查詢的欄位清單，請參閱 GoogleAdsField 說明文件。

程式碼範例

用戶端程式庫提供在 GoogleAdsService 中使用 Google Ads 查詢語言的範例。「basic operations」資料夾包含 GetCampaigns、GetKeywords 和 SearchForGoogleAdsFields 等範例。

查詢文法