10 月 16 日に、Google 広告と測定のコミュニティサーバーで Discord でのライブ配信にご参加ください。ここでは、Google Ads API の V22 で追加された新機能について説明します。

このページは Cloud Translation API によって翻訳されました。

スタートガイド

Apache Maven または Gradle でクライアントライブラリを使用することをおすすめします。

新しい Maven/Gradle プロジェクトを作成する

選択した IDE で新しい Maven プロジェクトまたは Gradle プロジェクトを作成します。Google のアーティファクトは Maven 中央リポジトリに公開されています。

依存関係のバージョンを管理するには、Google Ads API の部品構成表（BOM）を使用することをおすすめします。これは、他のフレームワークでも使用されている Guava や GAX などのライブラリとの依存関係の競合を回避する最善の方法です。BOM を使用すると、Google 広告クライアントライブラリでテスト済みのこれらの依存関係の正確なバージョンを使用できます。

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

<!-- Import the Bill of Materials (BOM) to ensure you're using compatible
     versions of all google-ads libraries. -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>google-ads-bom</artifactId>
      <version>40.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- Add the google-ads dependency, without a version. The version is
     managed by the BOM. -->
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
</dependency>

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

// Import the Bill of Materials (BOM).
implementation platform('com.google.api-ads:google-ads-bom:40.0.0')

// Add the google-ads dependency, without a version.
implementation 'com.google.api-ads:google-ads'

ソースからビルドすることもできます。このガイドでは、必要な依存関係が利用可能なプロジェクトが設定されていることを前提としています。

ソースからビルドする場合は、IDE でアノテーション処理を有効にしてください。

BOM でカバーされる依存関係の宣言

Google Ads API BOM には、Guava、Protobuf、GAX、gRPC などの一般的なライブラリのバージョン管理が含まれています。依存関係の競合を回避するため、BOM でカバーされる依存関係を宣言するときは、バージョンを指定しないでください。BOM はこれらのライブラリのバージョンを自動的に管理し、互換性を確保します。

たとえば、Maven で Guava 依存関係を宣言するには、次のようにします。

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <!-- NO VERSION SPECIFIED -->
</dependency>

Gradle の場合:

implementation 'com.google.guava:guava' // NO VERSION SPECIFIED

バージョンを省略すると、BOM でバージョンが管理されるため、互換性のない依存関係のバージョンに起因する問題を回避できます。依存関係の競合の一般的な指標には NoSuchMethodError や ClassNotFoundException があります。これらは、BOM で管理されるすべての依存関係にバージョンが指定されていないことを確認することで解決できることがよくあります。

API で認証するための認証情報を取得する

Google Ads API にアクセスするには、OAuth 認証情報と Google Ads API デベロッパートークンが必要です。このセクションでは、これらの内容、使用方法、取得方法について説明します。

デベロッパートークン（API へのアクセス用）

デベロッパートークンはクライアントセンター（MCC）アカウントにリンクされており、Google 広告のウェブインターフェースで確認できます。

開発者トークンは MCC アカウントにリンクされますが、そのアカウントへのアクセス権は付与されません。開発者トークンは、API へのアクセスを全般的に許可するものであり、アカウントレベルのアクセスは OAuth を介して構成されます。

OAuth 認証情報（Google 広告アカウントへのアクセス用）

Google 広告アカウントにアクセスできる Google アカウントユーザーとして認証するには、一連の OAuth 認証情報を提供する必要があります。

一般的に使用される OAuth フローには、デスクトップ（インストール済み）アプリとウェブアプリの 2 つがあります。この 2 つの主な違いは、デスクトップアプリではシステムブラウザを開き、Google の認証サーバーからのレスポンスを処理するためのローカルリダイレクト URI を指定する必要があるのに対し、ウェブアプリでは任意のサードパーティブラウザをリダイレクトして認証を完了し、認証情報をサーバーに送り返すことができるという点です。このライブラリは、あまり使用されないサービスアカウントフローもサポートしています。

独自の認証情報を使用して承認する場合（デスクトップアプリフロー）: OAuth デスクトップアプリのフローを参照してください。これには、独自の認証情報で認証するために必要なすべての詳細が含まれます。
サードパーティの Google ユーザーとして承認する場合（ウェブフロー）: OAuth ウェブアプリのフローを参照してください。これは、任意のサードパーティユーザーに対して OAuth 認証を設定する方法の例です。
Google Apps ドメインユーザーとして承認する場合（サービスアカウントフロー）: OAuth サービスアカウントのフローを参照してください。ここでは、Google Apps ドメインユーザーの OAuth 認証を設定する方法の例を示します。

Google 広告クライアントアカウントに Google 広告 MCC アカウント経由でアクセスしている場合は、以下のようにログインクライアント ID も指定する必要があります。

ログイン用のお客様 ID（MCC アカウント経由で Google 広告アカウントにアクセスする場合）

必要に応じて、配信アカウントへのアクセス権を付与するクライアントセンター（MCC）アカウントの顧客 ID を指定します。MCC アカウントからクライアントアカウントにアクセスしている場合は、この値を指定する必要があります。お客様 ID へのパスで、すべてのクライアントセンター（MCC）アカウントを指定する必要はありません。アクセス権限に使用している最上位の MCC ID のみを指定します。詳細については、関連ドキュメントをご覧ください。

認証情報を使用してクライアントライブラリを構成する

クライアントライブラリは、構成ファイル、環境変数、またはプログラムで構成できます。このガイドでは、構成ファイルアプローチを使用し、デスクトップとウェブのフローに焦点を当てます。認証情報が 1 つしかない場合（たとえば、1 つのクライアントセンターでアカウントを管理している場合）は、通常、構成ファイルを使用することをおすすめします。

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

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

プレースホルダは、前の手順で取得した認証情報に置き換えます。

また、更新トークンが MCC アカウントのものである場合は、このアカウントの顧客 ID をログイン顧客として指定する必要があります。

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

認証情報を検証する

すべてが正しく設定されていることを確認するために、GetCampaigns の例を実行します。

まず、google-ads-examples ディレクトリに移動します。

cd google-ads-examples

この例では、値が Google 広告アカウントのお客様 ID（ハイフンなし）である --customerId パラメータが必要です。

Gradle で実行するには:

./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

その他の例

google-ads-examples の examples パッケージには、いくつかの有用な例が含まれています。ほとんどの例ではパラメータが必要です。パラメータを引数として渡す（推奨）か、ソースコードで INSERT_XXXXX_HERE の値を編集します。使用状況ステートメントの例を表示するには、--help を唯一の引数として渡します。