本頁面由 Cloud Translation API 翻譯而成。

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 都代表一個填入所選欄位 (包括指定廣告活動的 resource_name) 的 campaign 物件。

如要瞭解可用於廣告活動查詢的其他欄位，請參閱 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 狀態且曝光次數超過 1, 000 次的廣告活動，同時依據廣告活動 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 參考說明文件。

根據查詢結果進行變動

查詢特定資源時，您可以立即將傳回的結果視為物件並進行修改，然後將結果傳回該資源的服務中的 var 方法。以下是工作流程範例：

針對目前是 PAUSED 且曝光次數超過 1000 的所有廣告活動執行查詢。
從回應中每個 GoogleAdsRow 的 campaign 欄位取得 Campaign 物件。
將每個廣告活動的狀態從「PAUSED」改為「ENABLED」。
使用修改的廣告活動呼叫 CampaignService.MutateCampaigns 以更新這些廣告活動。

欄位中繼資料

傳送至 GoogleAdsFieldService 的查詢旨在擷取欄位中繼資料。這項資訊可用於瞭解如何在查詢中同時使用這些欄位。因為資料可從 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 查詢語言的範例。基本作業資料夾具有範例，例如 GetCampaigns、GetKeywords 和 SearchForGoogleAdsFields。「reporting」資料夾具有 GetKeywordStats 範例。

查詢文法