開始使用 Ads Data Hub API

本指南介紹如何著手編寫使用 Ads Data Hub REST API 與廣告資料中心互動的應用程式。透過 Ads Data Hub REST API，您可以查看與 Google 帳戶相關聯的廣告資料中心客戶，以及建立和執行查詢。

設定

開始使用 Ads Data Hub API 前，您需要先完成幾個步驟：

1. 確認要啟用 API 的使用者已獲得 Google Cloud 專案的 serviceusage.services.enable 權限。必須將具有 serviceusage.services.enable 權限的使用者加入許可清單，他們才能存取 API。
2. 在已建立用戶端憑證或服務帳戶的 Google Cloud 專案中，啟用 Ads Data Hub API。如要透過控制台為專案啟用 Ads Data Hub API，請按照下列步驟操作：
   1. 前往 Cloud Console API 程式庫。
   2. 從專案清單中選取要使用的專案。
   3. 搜尋「Ads Data Hub API」。
   4. 在 API 頁面中，按一下「啟用」。
3. 管理權限：
   1. 必須將用於建立憑證的電子郵件地址或服務帳戶加到廣告資料中心，並授予適當的權限。如果是服務帳戶，這是指服務帳戶的電子郵件地址；如果是 OAuth，這是指使用者的電子郵件地址。這可以確保服務帳戶或使用者的帳戶有權在廣告資料中心執行查詢。
4. (建議) 安裝 Google API 用戶端程式庫：
   1. Google API 用戶端程式庫支援多種常用的語言，讓您可以使用多個 Google API。用戶端程式庫可減少您需要編寫的程式碼，並簡化驗證設定程序，您可視情況採用。

用戶端程式庫	廣告資料中心範例
適用於 Java 的 Google API 用戶端程式庫	Java
適用於 Python 的 Google API 用戶端程式庫

驗證與授權

Ads Data Hub API 可以存取並變更廣告資料中心客戶帳戶中的資料，因此您必須驗證自己是授權使用者。在開始使用 Ads Data Hub API 之前，請務必先完成授權流程，才能取得與 API 互動的必要權限。您可以使用 OAuth 2.0 或服務帳戶進行驗證。

OAuth 2.0 服務帳戶

OAuth 2.0 設定

API 支援安裝版應用程式和網頁應用程式流程。本文是以安裝版應用程式為例，將逐步說明相關流程。

1. 前往 Google API 控制台，然後前往您的管理員專案。
2. 確認專案已啟用 Ads Data Hub API。
   1. 如果尚未啟用，請按一下「+ 啟用 API 和服務」。
3. 在左側導覽列按一下「憑證」。
4. 開啟「建立憑證」下拉式選單，然後選取「OAuth 用戶端 ID」。在下方頁面中：
   1. 選取「其他」。
   2. (選用) 為用戶端命名。
   3. 按一下「建立」。
5. 在剛建立的憑證旁點按下載圖示。

取得 API 金鑰

下方的 Python 程式碼範例會使用您的 API 金鑰 (也稱為開發人員金鑰) 進行驗證。取得 API 金鑰的方法如下：

1. 前往 API 控制台的「憑證」頁面。
2. 確認您已在上方導覽列的下拉式選單中選取管理員專案。
3. 按一下 API 金鑰旁邊的下載圖示。

傳送範例要求

Python

"""This sample shows how to retrieve all accounts associated with the user.

For the program to execute successfully, ensure that you run it using Python 3.
"""
import json
from google_auth_oauthlib import flow
from googleapiclient.discovery import build

appflow = flow.InstalledAppFlow.from_client_secrets_file(
    # Replace client_secrets.json with your own client secret file.
    'client_secrets.json',
    scopes=['https://www.googleapis.com/auth/adsdatahub'])
appflow.run_local_server()
credentials = appflow.credentials
developer_key = input('Developer key: ').strip()
# For versions of the Google API Python client library prior to 2.0, the
# `static_discovery` parameter below should be removed.
service = build('AdsDataHub', 'v1', credentials=credentials,
                developerKey=developer_key, static_discovery=False)


def pprint(x):
  print(json.dumps(x, sort_keys=True, indent=4))


adh_account_id = input('ADH account ID (e.g. "customers/123456789"): ').strip()
pprint(service.customers().analysisQueries().list(parent
                                                  =adh_account_id).execute())

      

Java

/*
 * Copyright (c) 2019 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
 * in compliance with the License. You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License
 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
 * or implied. See the License for the specific language governing permissions and limitations under
 * the License.
 */

package com.google.api.services.samples.adsdatahub.cmdline;

import com.google.api.services.adsdatahub.v1.AdsDataHub;
import com.google.api.services.adsdatahub.v1.model.Customer;
import com.google.api.services.adsdatahub.v1.model.ListCustomersResponse;
import java.io.IOException;
import java.util.List;

/**
 * This sample illustrates how to retrieve all accounts associated to the user.
 *
 * <p>See the <a href="customers.list reference
 * documentation">https://developers.google.com/ads-data-hub/reference/rest/v1/customers/list</a>
 * for more details.
 */
public class ListCustomers extends BaseSample {

  @Override
  public String getName() {
    return "List customers";
  }

  @Override
  public String getDescription() {
    return "Lists customers associated with the authorized user";
  }

  @Override
  public void execute(AdsDataHub client) throws IOException {
    String pageToken = null;
    boolean noData = true;

    System.out.println("========================================");
    System.out.printf("Listing of customers associated with the authorized user:\n");
    System.out.println("========================================");

    do {
      ListCustomersResponse response = client.customers().list().setPageToken(pageToken).execute();
      pageToken = response.getNextPageToken();
      List<Customer> customers = response.getCustomers();

      if (customers != null && customers.size() > 0) {
        noData = false;
        for (Customer customer : customers) {
          System.out.printf("* Customer id: %d\n", customer.getCustomerId());
          System.out.printf("\tCustomer name: %s\n", customer.getDisplayName());
        }
      }
    } while (pageToken != null);

    if (noData) {
      System.out.println("No customers were found associated with the authorized user.");
    }
  }
}

      

後續步驟

• 想進一步瞭解使用 Ads Data Hub REST API 可建立及執行哪些查詢，請參閱廣告資料中心的查詢範例。
• 請展開範例內容，熟悉 API 的用法並根據自己的用途自訂，然後嘗試：
  • 輪詢查詢作業狀態。
  • 使用 BigQuery 用戶端程式庫擷取已完成的查詢結果。
• 如果對 API 有任何疑問或意見，請與廣告資料中心支援團隊聯絡。