開始使用 Search Ads 360 Reporting API

以下各節說明如何開始使用 Search Ads 360 Reporting API。

在 Google Cloud 上設定專案

如要使用 Search Ads 360 Reporting API，您需要在 Google Cloud 上為應用程式建立專案。

建立 Google 專案

Google 專案可做為 Google Cloud 資源的資源容器。

  1. Go to the Google API Console.
  2. 單擊創建項目 。
  3. 輸入名稱或接受生成的建議。
  4. 確認或編輯所有剩餘字段。
  5. 點擊創建 。

建立 OAuth2 憑證

Search Ads 360 Reporting API 會使用 OAuth 2.0 進行驗證及授權。OAuth 憑證會向 Google 識別您的應用程式，並可讓您產生 OAuth 權杖來管理 Search Ads 360 使用者。

要在Google API Console創建OAuth 2.0憑據，請執行以下操作：

  1. Go to the Credentials page.
  2. 點擊創建憑據> OAuth客戶端ID
  3. 選擇您的應用程序類型。
  4. 填寫表格，然後點擊創建 。

啟用 Search Ads 360 Reporting API

如要使用 API，您必須在 Google API 控制台中為專案啟用 Search Ads 360 Reporting API。

為您的項目啟用API：

  1. Open the API Library中的Google API Console 。
  2. If prompted, select a project, or create a new one. API Library列出了所有可用的API，並按產品系列和受歡迎程度分組。
  3. 如果您要啟用的API在列表中不可見，請使用搜索找到它，或單擊其所屬產品系列中的“ 查看全部 ”。
  4. 選擇要啟用的API，然後單擊“ 啟用”按鈕。
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

視需要啟用專案的計費功能

不必為在 Google Cloud 中使用 Search Ads 360 Reporting API 付費。 不過，每個帳戶的免費 Cloud 專案總數有其配額。如果您已達到上限，可以註冊新的 Google 帳戶，其中包含免費專案配額。

為您的項目啟用計費：

  1. 訪問Billing page 。
  2. 如果您沒有有效的帳單帳戶，請點擊添加帳單帳戶並按照說明創建帳戶 。

要啟用項目的同意屏幕：

  1. 在Consent Screen page中打開Google API Console 。
  2. If prompted, select a project, or create a new one.
  3. 填寫表格，然後點擊保存 。

建立、編輯或查看重新導向 URI

要創建，查看或編輯給定OAuth 2.0憑據的重定向URI，請執行以下操作：

  1. Go to the Credentials page.
  2. 在頁面的OAuth 2.0客戶端ID部分中，點擊一個憑據。
  3. 查看或編輯重定向URI。

如果“憑據”頁面上沒有OAuth 2.0客戶端ID部分，則您的項目沒有OAuth憑據。要創建一個，點擊創建憑證 。

下載用戶端程式庫

建議您使用 Search Ads 360 Reporting API 用戶端程式庫來連結 Search Ads 360 Reporting API。

下載適用於開發環境的 Search Ads 360 Reporting API 用戶端程式庫。請按照語言特定的操作說明設定用戶端程式庫設定檔。在大多數情況下，在遷移至新版 Search Ads 360 Reporting API 用戶端程式庫時，您可以重複使用現有設定。

重要的是新的 login-customer-id 標頭。如要進一步瞭解何時需要將其新增至設定，請參閱「登入客戶 ID 標頭」。

撥打你的第一通電話

設定用戶端程式庫後，即可進行第一個呼叫。

取得廣告活動

在 IDE 中執行以下程式碼：

Java

// Copyright 2022 Google LLC
//
// 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
//
//     https://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 sample;

import com.beust.jcommander.Parameter;
import com.google.ads.searchads360.v0.lib.SearchAds360Client;
import com.google.ads.searchads360.v0.services.SearchAds360Row;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient;
import com.google.ads.searchads360.v0.services.SearchAds360ServiceClient.SearchPagedResponse;
import com.google.ads.searchads360.v0.services.SearchSearchAds360Request;

/** Get campaign details. */
public class GetCampaigns {
  private static final int PAGE_SIZE = 200;

  private static class GetCampaignsParams extends CodeSampleParams {

    @Parameter(names = "--customerId", required = true)
    private String customerId;

    @Parameter(names = "--loginCustomerId")
    private String loginCustomerId;
  }

  public static void main(String[] args) {
    GetCampaignsParams params = new GetCampaignsParams();
    if (!params.parseArguments(args)) {
      // Optional: You may pass the loginCustomerId on the command line or specify a loginCustomerId
      // here (10 digits, no dashes). If neither are set, customerId will be used as
      // loginCustomerId.
      // params.loginCustomerId = Long.parseLong("INSERT_LOGIN_CUSTOMER_ID_HERE");
    }
    final String loginCustomerId = params.loginCustomerId;
    final String customerId = params.customerId;

    try {
      // Creates a SearchAds360Client with the specified loginCustomerId. If there's
      // no loginCustomerId, customerId will be used instead.
      final SearchAds360Client searchAds360Client =
          SearchAds360Client.newBuilder()
              .setLoginCustomerId(loginCustomerId == null ? customerId : loginCustomerId)
              .fromPropertiesFile()
              .build();
      // Creates the Search Ads 360 Service client.
      SearchAds360ServiceClient client = searchAds360Client.create();
      new GetCampaigns().runExample(client, customerId);
    } catch (Exception exception) {
      System.err.printf("Failed with exception: %s%n", exception);
      exception.printStackTrace();
      System.exit(1);
    }
  }

  private void runExample(SearchAds360ServiceClient searchAds360ServiceClient, String customerId) {
    // Creates a query that retrieves all campaigns under the customerId.
    String query = "SELECT campaign.name, campaign.id, campaign.status FROM campaign";
    SearchSearchAds360Request request =
        SearchSearchAds360Request.newBuilder()
            .setCustomerId(customerId)
            .setQuery(query)
            .setPageSize(PAGE_SIZE)
            .build();

    // Issues a search request.
    final SearchPagedResponse searchPagedResponse = searchAds360ServiceClient.search(request);
    for (SearchAds360Row element : searchPagedResponse.iterateAll()) {
      System.out.printf(
          "Campaign found with name '%s', ID %d, and status: %s.%n",
          element.getCampaign().getName(),
          element.getCampaign().getId(),
          element.getCampaign().getStatus());
    }
  }
}

下載 Get 廣告活動.java

Python

#!/usr/bin/env python
# Copyright 2022 Google LLC
#
# 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
#
#     https://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.
"""Retrieves campaigns for a customer using a pagination search request."""

import argparse
import traceback
from google.ads.searchads360.v0.services.types.search_ads360_service import SearchSearchAds360Request
from util_searchads360 import SearchAds360Client

_DEFAULT_PAGE_SIZE = 10000


def main(client, customer_id, page_size) -> None:
  search_ads_360_service = client.get_service()

  query = """
      SELECT
        campaign.name,
        campaign.id,
        campaign.status
      FROM campaign"""

  request = SearchSearchAds360Request()
  request.customer_id = customer_id
  request.query = query
  request.page_size = page_size

  # Issues a search request.
  results = search_ads_360_service.search(request=request)

  for row in results:
    campaign = row.campaign
    print(
        f'campaign "{campaign.name}" has id {campaign.id} and status {campaign.status.name}'
    )


if __name__ == "__main__":
  # SearchAds360Client will read the search-ads-360.yaml configuration file in
  # the home directory if none is specified.
  search_ads_360_client = SearchAds360Client.load_from_file()

  parser = argparse.ArgumentParser(
      description=("Retrieves campaigns for a customer."))
  # Arguments to provide to run the example.
  parser.add_argument(
      "-c",
      "--customer_id",
      type=str,
      required=True,
      help="The Search Ads 360 customer ID (10 digits, no dashes).",
  )

  parser.add_argument(
      "-l",
      "--login_customer_id",
      type=str,
      required=False,
      help="The Search Ads 360 login customer ID (10 digits, no dashes).",
  )

  args = parser.parse_args()

  search_ads_360_client.set_ids(args.customer_id, args.login_customer_id)

  try:
    main(search_ads_360_client, args.customer_id, _DEFAULT_PAGE_SIZE)
  except Exception:  # pylint: disable=broad-except
    traceback.print_exc()

下載 get_campaigns.py

控制台會列印您帳戶中的廣告活動清單。

使用 REST

如果您決定不使用用戶端程式庫，就必須瞭解如何使用 REST。

如果您搭配舊版 Search Ads 360 API 使用 REST，您的憑證仍可搭配新版 Search Ads 360 Reporting API 使用。在 REST 參考資料部分找到新端點和其他詳細資料。

瞭解詳情

進一步瞭解 Search Ads 360 Reporting API