クイック スタート

このクイック スタートガイドでは、Google Ads API への最初の API 呼び出しを行う方法について説明します。

主なコンセプト

• デベロッパー トークン: デベロッパー トークンは、Google Ads API サーバーに対してアプリを識別する 22 文字の英数字文字列です。API 呼び出しを行うために必要です。
• API アクセスレベル: 開発者トークンの API アクセスレベルによって、1 日あたりに実行できる API 呼び出しの回数と、API 呼び出しを実行できる環境が制御されます。
• Google 広告の MCC アカウント: Google 広告の MCC アカウントは、他の Google 広告アカウントの管理に使用されます。Google 広告クライアント センター（MCC）アカウントは、Google 広告クライアント アカウントや他の Google 広告クライアント センター（MCC）アカウントの管理に使用できます。開発者トークンを取得するには、Google 広告クライアント センター（MCC）アカウントが必要です。
• Google 広告クライアント アカウント: API 呼び出しの対象となる Google 広告アカウント。
• クライアントのお客様 ID: Google 広告クライアント アカウントを識別する 10 桁の番号。
• OAuth 2.0: OAuth 2.0 は、すべての Google API で使用されている業界標準の承認プロトコルです。API 呼び出しを行うための OAuth 2.0 認証情報を生成するには、サービス アカウントとキーが必要です。
• Google Cloud プロジェクト: Google Cloud プロジェクトは、API と OAuth 2.0 API 認証情報の管理など、すべての Google サービスの作成、有効化、使用の基礎となります。Google Cloud Console から作成できます。
• サービス アカウント: 個々のユーザーではなくアプリケーションに属する特殊なタイプの Google アカウント。これは、Google Ads API に対してアプリケーションを認証するために使用されます。サービス アカウントを取得するには、Google Cloud プロジェクトが必要です。
• サービス アカウント キー: サービス アカウントの秘密鍵を含む JSON アプリ認証情報ファイル。これは、Google Ads API API 呼び出しを行うときにサービス アカウントを認証するための OAuth 2.0 認証情報の生成に使用されます。サービス アカウント キーを取得するには、サービス アカウントが必要です。

前提条件

Google Ads API 呼び出しを行うには、次の手順を完了する必要があります。

デベロッパー トークンを取得する

キーポイント: この手順で取得した開発者トークンとそのアクセスレベルをメモしておきます。デベロッパー トークンは、22 文字の英数字の文字列です。この情報は、API 呼び出しを行う際に必要になります。

過去に開発者トークンに登録したことがある場合は、Google 広告クライアント センター（MCC）アカウントにログインした状態で API センターにアクセスすると、開発者トークンを確認できます。

API Center にアクセスする

開発者トークンをお持ちでない場合は、API センターで登録できます。

デベロッパー トークンに登録する方法

1. ウェブブラウザで API Center に移動します。メッセージが表示されたら、Google 広告の MCC アカウントにログインします。 まだお持ちでない場合は、Google 広告クライアント センター（MCC）アカウントを作成します。
2. API アクセス フォームに必要事項を入力し、利用規約に同意します。
   • 情報が正しく、会社のウェブサイトの URL が機能していることを確認します。ウェブサイトが公開されていない場合、Google は申請を処理できず、不承認となる可能性があります。
   • 指定した API 連絡先のメールアドレスが、定期的にモニタリングされている受信トレイにつながっていることを確認します。Google の API コンプライアンス チームは、審査プロセス中にこのメールアドレスに連絡して、説明を求めることがあります。ご連絡が取れない場合、Google は申請手続きを続行しないことがあります。
   • API 連絡先メールアドレスは、API センターで編集できます。Google から重要なサービスに関するお知らせをお送りできるように、申請手続き後もこの情報を最新の状態に保ってください。

申請手続きが完了すると、API センターに開発者トークンが表示され、ステータスは [Pending Approval]（承認待ち）になります。デベロッパー トークンのアクセスレベルが Test Account Access になりました。

Google API Console プロジェクトを構成する

重要なポイント: このステップで生成するサービス アカウントのメールアドレスとサービス アカウント キーの両方をメモしておきます。API 呼び出しを行う際に必要になります。

Google API Console プロジェクトは、Google API と OAuth 2.0 API 認証情報の管理に使用されます。既存の Google API Console プロジェクトを確認するか、新しいプロジェクトを作成するには、Google API Console にアクセスします。

Google API コンソールを開く

まず、プロジェクトで Google Ads API を有効にします。

Google Ads API を有効にする

次に、API 呼び出しを行うためのサービス アカウントとサービス アカウント キーが必要です。別の Google API をすでに使用しており、OAuth 2.0 サービス アカウントとキーを作成している場合は、この手順を省略して既存の認証情報を再利用できます。

サービス アカウントとキーを作成する方法

1. Google Cloud コンソールで、メニュー > [IAM と管理] > [サービス アカウント] に移動します。

   [サービス アカウント] に移動

2. サービス アカウントを選択します。
3. [鍵] > [鍵を追加] > [新しい鍵を作成] をクリックします。
4. [JSON] を選択し、[作成] をクリックします。

   新しい公開鍵と秘密鍵のペアが生成され、新しいファイルとしてパソコンにダウンロードされます。ダウンロードした JSON ファイルを作業ディレクトリに credentials.json として保存します。このファイルはこの鍵の唯一のコピーです。

5. [閉じる] をクリックします。

Google 広告クライアント アカウントを設定する

キーポイント: 10 桁の Google 広告クライアントのお客様 ID をメモします。 この ID は、API 呼び出しの対象となるアカウントを指定するために必要です。

まず、API 呼び出しの対象となる Google 広告アカウントを特定します。API 呼び出しを行うことができるアカウントの種類は、デベロッパー トークンの API アクセス権によって異なります。API アクセスレベルを確認するには、API Center をご覧ください。

ベーシック アクセスレベルとスタンダード アクセスレベル

Google 広告の本番環境アカウントに呼び出しを行うことができます。ただし、必要に応じて、[テスト アカウントへのアクセス] タブの手順に沿って Google 広告テスト アカウントを作成できます。

テスト アカウントのアクセス権

開発者トークンを使用して、Google 広告の本番環境アカウントに対して API 呼び出しを行うことはできません。API 呼び出しは、Google 広告のテスト アカウントに対してのみ行うことができます。

Google 広告のテストアカウントを作成する方法

以下の手順では、Google 広告のテスト用 MCC アカウントと、その下に Google 広告のテスト用広告主アカウントを作成します。

1. 青いボタンをクリックして、Google 広告のテスト用 MCC アカウントを作成します。 メッセージが表示されたら、Google 広告のプロダクション マネージャー アカウントにリンクされていない Google アカウントでログインします。アカウントをお持ちでない場合は、このページの [アカウントを作成] ボタンを使用して、新しい Google アカウントを作成します。

   Google 広告のテスト用クライアント センター（MCC）アカウントを作成する

2. Google 広告のテスト用 MCC アカウントで、Google 広告のテスト用クライアント アカウントを作成します。[アカウント > > 新しいアカウントを作成] をクリックして、フォームに記入します。Google 広告のテスト用 MCC アカウントから作成した Google 広告アカウントは、すべて自動的に Google 広告のテスト アカウントになります。
3. 必要に応じて、Google 広告ページから Google 広告のテスト用クライアント アカウントにキャンペーンをいくつか作成します。

Google 広告のお客様に対して API 呼び出しを行うには、Google 広告のお客様アカウントに対するアクセス権と適切な権限をサービス アカウントに付与する必要があります。この操作を行うには、お客様のアカウントの管理者権限が必要です。

サービス アカウントに Google 広告アカウントへのアクセス権を付与する方法

1. まず、管理者として Google 広告アカウントにログインします。
2. [管理者] > [アクセスとセキュリティ] に移動します。
3. [ユーザー] タブの [] ボタンをクリックします。
   
4. [メール] 入力ボックスにサービス アカウントのメールアドレスを入力します。適切なアカウントのアクセス権限を選択し、[アカウントを追加] ボタンをクリックします。サービス アカウントではメール アクセス レベルはサポートされていません。
   
5. サービス アカウントにアクセス権が付与されます。
   
6. [省略可] デフォルトでは、サービス アカウントに管理者アクセス権を付与することはできません。API 呼び出しに管理者権限が必要な場合は、次のようにアクセス権をアップグレードできます。
   1. [アクセスレベル] 列で、サービス アカウントのアクセスレベルの横にあるプルダウン矢印をクリックします。
   2. プルダウン リストから [管理者] を選択します。

ツールとクライアント ライブラリをダウンロードする

API 呼び出しの方法に応じて、クライアント ライブラリまたは HTTP クライアントをダウンロードできます。

クライアント ライブラリを使用する

選択したクライアント ライブラリをダウンロードしてインストールします。

HTTP クライアント（REST）を使用する

curl

URL を介してデータを転送するためのコマンドライン ツールである curl をダウンロードしてインストールします。

Google Cloud CLI

手順に沿って gcloud CLI をインストールします。

このガイドの残りの手順は、次のバージョンの gcloud ツールで動作することを確認しています。アプリケーションの動作やコマンドライン オプションの違いにより、以前のバージョンでは動作しない可能性があります。

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

API 呼び出しを行う

重要なポイント: クライアント ライブラリの手順では、login_customer_id という追加の設定が参照されています。このガイドを完了するには、この設定に 10 桁のお客様 ID を指定します。このガイドを完了したら、[Google 広告のアクセスモデル][link-accessmodel] を読んで、この設定について詳しく確認してください。

注: クライアント ライブラリの手順では、特定のライブラリ バージョンを参照している場合があります。これは説明のみを目的としています。明示的に指定されていない限り、クライアント ライブラリの最新バージョンを使用できます。

API 呼び出しを行う方法については、使用するクライアントを選択してください。

Java

クライアント ライブラリのアーティファクトは、Maven 中央リポジトリに公開されています。次のように、クライアント ライブラリを依存関係としてプロジェクトに追加します。

Maven 依存関係は次のとおりです。

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>40.0.0</version>
</dependency>

Gradle の依存関係は次のとおりです。

implementation 'com.google.api-ads:google-ads:40.0.0'

次の内容の ~/ads.properties ファイルを作成します。

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

GoogleAdsClient オブジェクトは、次のように作成します。

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}
GetCampaigns.java

C#

クライアント ライブラリ パッケージは Nuget.org リポジトリに公開されています。まず、Google.Ads.GoogleAds パッケージへの nuget 参照を追加します。

dotnet add package Google.Ads.GoogleAds --version 18.1.0

関連する設定で GoogleAdsConfig オブジェクトを作成し、それを使用して GoogleAdsClient オブジェクトを作成します。

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V21.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
GetCampaigns.cs

PHP

クライアント ライブラリ パッケージは Packagist リポジトリに公開されています。プロジェクトのルート ディレクトリに移動し、次のコマンドを実行して、ライブラリとそのすべての依存関係をプロジェクトのルート ディレクトリの vendor/ ディレクトリにインストールします。

composer require googleads/google-ads-php:31.0.0

GitHub リポジトリから google_ads_php.ini ファイルのコピーを作成し、認証情報を含めるように変更します。

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/adwords"

GoogleAdsClient オブジェクトのインスタンスを作成します。

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}
GetCampaigns.php

Python

クライアント ライブラリは PyPI で配布されており、次のように pip コマンドを使用してインストールできます。

python -m pip install google-ads==21.3.0

GitHub リポジトリから google-ads.yaml ファイルのコピーを作成し、認証情報を含めるように変更します。

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

GoogleAdsClient.load_from_storage メソッドを呼び出して、GoogleAdsClient インスタンスを作成します。google-ads.yaml のパスを文字列としてメソッドに渡します。

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

ログの出力先をライブラリのロガーに伝えるハンドラを追加します。次のコードは、ライブラリのロガーにコンソール（stdout）への出力を指示します。

import logging
import sys

logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )
get_campaigns.py

Ruby

クライアント ライブラリの Ruby gem は、Rubygems gem ホスティング サイトに公開されています。インストールには bundler を使用することをおすすめします。Gemfile に次の行を追加します。

gem 'google-ads-googleads', '~> 35.2.0'

次のコマンドを実行します。

bundle install

GitHub リポジトリから google_ads_config.rb ファイルのコピーを作成し、認証情報を含めるように変更します。

Google::Ads::GoogleAds::Config.new do |c|
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end

このファイルを保存しているパスを渡して、GoogleAdsClient インスタンスを作成します。

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
end
get_campaigns.rb

Perl

このライブラリは CPAN で配布されています。まず、任意のディレクトリに google-ads-perl リポジトリのクローンを作成します。

git clone https://github.com/googleads/google-ads-perl.git

google-ads-perl ディレクトリに移動し、コマンド プロンプトで次のコマンドを実行して、ライブラリの使用に必要なすべての依存関係をインストールします。

cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps

GitHub リポジトリから googleads.properties ファイルのコピーを作成し、認証情報を含めるように変更します。

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

このファイルを保存している場所へのパスを渡して、Client インスタンスを作成します。

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V21::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}
get_campaigns.pl

curl

まず、gcloud CLI でサービス アカウントをアクティブな認証情報として設定します。

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

次に、Google Ads API の OAuth 2.0 アクセス トークンを取得します。

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

次に、GoogleAdsService.SearchStream メソッドを使用してキャンペーン レポートを実行し、アカウント内のキャンペーンを取得します。このガイドでは、レポートの詳細については説明しません。

curl -i -X POST https://googleads.googleapis.com/v21/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

query.json の内容は次のとおりです。

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}