開始使用 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());
    }
  }
}

下載 GetCampaigns.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。

如果您曾使用 REST 搭配舊版 Search Ads 360 API，您的憑證仍可搭配新版 Search Ads 360 Reporting API 使用。請參閱 REST 參考資料章節，瞭解新端點和其他詳細資訊。

瞭解詳情

進一步瞭解 Search Ads 360 Reporting API