最初の API 呼び出しを実行する

このガイドでは、最初の API 呼び出しを実行するまでの手順を詳しく解説します。AdWords API を最大限に活用するための最初の一歩となります。

動画では Java と Eclipse を使用しますが、自分に合った言語とクライアント ライブラリを選んで使用できます。別の言語を選択した場合でも考え方は同様で、対応している言語ごとの設定手順についても以下で説明します。

設定手順の概要

API アクセスを設定するには、必要な認証情報を取得してテスト アカウントを作成し、認証情報とアカウントのデータをクライアント ライブラリの設定ファイルに追加します。

この設定ファイルを作成したら、API 呼び出しを実行する準備は完了です。

主要な手順は以下の 6 つです。

  1. 開発者トークンをリクエストする
  2. テスト アカウントを作成する
  3. クライアント ライブラリを取得する
  4. OAuth2 で認証を設定する
  5. OAuth2 リフレッシュ トークンを取得してクライアントを設定する
  6. 最初の API 呼び出しを実行する

各手順について、以下のセクションで説明していきます。

開発者トークンをリクエストする

Google から発行される開発者トークンを利用することで、アプリケーションと AdWords API を接続できます。このトークンは、ご利用開始ガイドの手順に従って取得してください(まだ取得していない場合)。ご利用開始の手続きを終えると、承認待ちの開発者トークンが届きます。

本番用の AdWords アカウントでは、承認済みの開発者トークンを使用する必要があります。

テスト アカウントを作成する

以下の手順に従ってテスト用の MCC アカウントとテスト用のクライアント アカウントを開設し、テスト用のアカウントにキャンペーンをいくつか作成します。

  1. AdWords MCC アカウントのページに移動してテスト用の MCC アカウントを作成します。
  2. AdWords の管理画面で、作成した MCC アカウントの配下にテスト用のクライアント アカウントを作成します。テスト用の MCC アカウントで AdWords にログインしてから作成したアカウントは、すべて自動的にテスト用のアカウントとなります。
  3. AdWords の管理画面で、テスト用のクライアント アカウント内にテスト用のキャンペーンをいくつか作成します。
  4. 新規作成したテスト用のクライアント アカウントのお客様 ID のメモをとり、保管しておいてください。この ID は後で設定ファイルに追加します。クライアント アカウントのお客様 ID は以下のように表示されます。

本番用の MCC アカウントの開発者トークンを使用してテスト用の MCC アカウントへのリクエストを実行します。トークンは、まだ承認されていなくても、さきほど作成したものを含むテスト用のアカウントで使用することができます。

クライアント ライブラリを取得する

クライアント ライブラリによってバックエンドの API 呼び出しがすべて処理されるほか、あらゆるタイプの一般的な API タスクに適したコードのサンプルなど、便利なオブジェクトを利用できます。

経験豊富な開発者の方であれば、既に最適な開発環境が整っているかもしれませんが、まだ環境を設定していない方のためにクライアント ライブラリの推奨の設定手順を説明します。

以下で使用する言語に対応するタブをクリックし、表示された手順に従ってください。

Java

  1. GitHub で Java クライアント ライブラリの README ファイル内の Getting Started セクションを参照し、Java 用の AdWords API クライアント ライブラリをダウンロードしてインストールします。
  2. このページに戻り、以下の手順に従って OAuth2 の認証などの各種設定を済ませます。

.NET

  1. .NET クライアント ライブラリの README ファイル内の Getting Started セクションを参照し、CSharp または Visual Basic 用の AdWords API クライアント ライブラリをダウンロードしてインストールします。
  2. このページに戻り、以下の手順に従って OAuth2 の認証などの各種設定を済ませます。

Python

  1. Python クライアント ライブラリの README ファイル内の Getting Started セクションを参照し、Python 用の AdWords API クライアント ライブラリをダウンロードしてインストールします。
  2. このページに戻り、以下の手順に従って OAuth2 の認証などの各種設定を済ませます。

PHP

  1. PHP クライアント ライブラリの README ファイル内の Getting Started セクションを参照し、PHP 用の AdWords API クライアント ライブラリをダウンロードしてインストールします。
  2. このページに戻り、以下の手順に従って OAuth2 の認証などの各種設定を済ませます。

Perl

  1. Perl クライアント ライブラリの README ファイル内の Getting Started セクションを参照し、Perl 用の AdWords API クライアント ライブラリをダウンロードしてインストールします。
  2. このページに戻り、以下の手順に従って OAuth2 の認証などの各種設定を済ませます。

Ruby

  1. Ruby クライアント ライブラリの README ファイル内の Getting Started セクションを参照し、Ruby 用の AdWords API クライアント ライブラリをダウンロードしてインストールします。
  2. このページに戻り、以下の手順に従って OAuth2 の認証などの各種設定を済ませます。

OAuth2 認証を設定する

アプリケーションがユーザーデータを参照し、ユーザーの代わりに他の Google サービスにアクセスできるようにする必要があります。OAuth2 認証を利用すれば、ユーザーのアカウントの代わりにアプリケーションで各種処理を実行できるようになります。

アプリケーションが API にアクセスできるようにするには、OAuth2 クライアント IDクライアント シークレットが必要です。

  1. MCC アカウントの認証情報でログインしてから、Google Developers Console の認証に関するページを開きます。
  2. [プロジェクトの作成] をクリックしてプロジェクト名を入力し、[作成] をクリックします。
  3. [認証情報を作成]、[OAuth クライアント ID] の順にクリックします。
  4. [同意] 画面でのプロダクト名の設定を促された場合は、[同意画面を設定] をクリックして必要な情報を入力してから、[保存] をクリックして [認証情報] 画面に戻ります。
  5. [アプリケーションのタイプ] で、このチュートリアル用の [その他] を選択します。指定された欄に名前を入力します。
  6. [作成] をクリックします。OAuth2 クライアント ID とクライアント シークレットが表示されるので、コピーします。この 2 つの情報は次の手順で設定ファイルに追加します。

OAuth2 リフレッシュ トークンを取得してクライアントを設定する

OAuth2 アクセスは一定期間後に有効期限が切れるため、OAuth2 リフレッシュ トークンを使用して自動的に OAuth2 アクセスを更新します。

使用するプログラム言語に対応するタブをクリックしてから、表示された手順に従って OAuth2 リフレッシュ トークンを生成し、クライアントの設定ファイルを作成します。

Java

  1. GitHub のこちらの手順に従って OAuth2 リフレッシュ トークンを取得し、クライアント ライブラリを設定します。
  2. 完了したらこのページに戻ります。手順を終えると、テスト用 API 呼び出しの実行に必要なすべてのデータが ads.properties ファイルに揃います。
[...]
api.adwords.developerToken=123axxxxxxxxxxxxxxxxxx
api.adwords.clientId=xxxxxxxxxx.apps.googleusercontent.com
api.adwords.clientSecret=zZxxxxxTxxxxxxxxxxx
api.adwords.clientCustomerId=123-456-7890
api.adwords.refreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
api.adwords.userAgent=Company_Name
[...]

.NET

  1. GitHub のこちらの手順に従って OAuth2 リフレッシュ トークンを取得し、クライアント ライブラリを設定します。
  2. 完了したらこのページに戻ります。手順を終えると、テスト用 API 呼び出しの実行に必要なすべてのデータが app.config ファイルに揃います。
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="AdWordsApi"
        type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <AdWordsApi>
    <!-- Settings specific to AdWords API.-->
    <add key="UserAgent" value="My AdWords API application"/>
    <add key="DeveloperToken" value="xxxxxxxxxxxxxxxxxxxxxx"/>
    <add key="ClientCustomerId" value="123-456-7890"/>

    <!-- OAuth2 configuration -->
    <add key="AuthorizationMethod" value="OAuth2" />
    <add key="OAuth2ClientId" value="xxxxxxxxxx.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="zZxxxxxTxxxxxxxxxxx" />
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2RefreshToken" value="1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxx" />
  </AdWordsApi>
</configuration>

Python

  1. GitHub のこちらの手順に従って OAuth2 リフレッシュ トークンを取得し、クライアント ライブラリを設定します。
  2. 完了したらこのページに戻ります。手順を終えると、テスト用 API 呼び出しの実行に必要なすべてのデータが googleads.yaml 設定ファイルに揃います。
adwords:
  developer_token: 123axxxxxxxxxxxxxxxxxx
  user_agent: Company_Name
  client_customer_id: 123-456-7890
  client_id: xxxxxxxxxx.apps.googleusercontent.com
  client_secret: zZxxxxxTxxxxxxxxxxx
  refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

PHP

  1. GitHub のこちらの手順に従って OAuth2 リフレッシュ トークンを取得し、クライアント ライブラリを設定します。
  2. 完了したらこのページに戻ります。手順を終えると、テスト用 API 呼び出しの実行に必要なすべてのデータが auth.ini 設定ファイルに揃います。
[...]
developerToken = 123axxxxxxxxxxxxxxxxxx
userAgent = Company_Name
clientCustomerId = 123-456-7890
client_id = xxxxxxxxxx.apps.googleusercontent.com
client_secret = zZxxxxxTxxxxxxxxxxx
refresh_token = 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Perl

  1. GitHub のこちらの手順に従って OAuth2 リフレッシュ トークンを取得し、クライアント ライブラリを設定します。
  2. 完了したらこのページに戻ります。手順を終えると、テスト用 API 呼び出しの実行に必要なすべてのデータが adwords.properties 設定ファイルに揃います。
[...]
userAgent = Company_Name
developerToken=123axxxxxxxxxxxxxxxxxx
clientId=123-456-7890
oAuth2ClientId=xxxxxxxxxx.apps.googleusercontent.com
oAuth2ClientSecret=zZxxxxxTxxxxxxxxxxx
oAuth2RefreshToken=1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
[...]

Ruby

  1. GitHub のこちらの手順に従って OAuth2 リフレッシュ トークンを取得し、クライアント ライブラリを設定します。
  2. 完了したらこのページに戻ります。手順を終えると、テスト用 API 呼び出しの実行に必要なすべてのデータが adwords_api.yml 設定ファイルに揃います。
[...]
:oauth2_client_id: xxxxxxxxxx.apps.googleusercontent.com
:oauth2_client_secret: zZxxxxxTxxxxxxxxxxx
:refresh_token: 1/dyOIp7ki-xxxxxxxxxxxxxxxxxxxxxxxx
:developer_token: 123axxxxxxxxxxxxxxxxxx
:client_customer_id: 123-456-7890
:user_agent: Company_Name
[...]

最初の API 呼び出しを実行する

環境と設定ファイルの準備が整ったら、最初の API 呼び出しを実行します。

Java

  1. IDE で GetCampaigns.java を開いて実行します。
  2. 上記の手順でテスト用のアカウントに追加したテスト用キャンペーンのリストが出力されます。

.NET

  1. IDE で GetCampaigns.cs または GetCampaigns.vb を開いて実行します。
  2. 上記の手順でテスト用のアカウントに追加したテスト用キャンペーンのリストが出力されます。

Python

  1. IDE で get_campaigns.py を開いて実行します。
  2. 上記の手順でテスト用のアカウントに追加したテスト用キャンペーンのリストが出力されます。

PHP

  1. IDE で GetCampaigns.php を開いて実行します。
  2. 上記の手順でテスト用のアカウントに追加したテスト用キャンペーンのリストが出力されます。

Perl

  1. IDE で get_campaigns.pl を開いて実行します。
  2. 上記の手順でテスト用のアカウントに追加したテスト用キャンペーンのリストが出力されます。

Ruby

  1. コマンドラインで以下を入力し、get_campaigns.rb を実行します。
    ruby get_campaigns.rb
  2. 上記の手順でテスト用のアカウントに追加したテスト用キャンペーンのリストが出力されます。

これで最初の AdWords API 呼び出しが実行されました。

このセクションでは多数のポイントを説明しました。次のセクションでは、今回扱った設定要素のいくつかについて、より詳細に解説します。

設定要素の解説

前のセクションでは、最初の API 呼び出しを実行するためのすべての設定を行いました。

このセクションでは、AdWords API の呼び出しで使用したアプリケーションの設定要素を見直しながら、より詳細に解説します。

テスト用と本番用のアカウント

前のセクションでは、テスト用の MCC アカウントとテスト用のクライアント アカウントを作成しました。

テスト アカウントは実際の広告掲載に影響したり料金が発生したりしないため、API を試す際に便利です。掲載結果に影響を与えることなく AdWords の管理画面を試すこともできます。

AdWords の管理画面にログインすると、明るい赤色の文字で [テスト アカウント] というラベルが表示され、そのアカウントがテスト用であることがわかります。

テスト アカウントでは実際に広告が配信されることはないため、通常はレポートや API 呼び出しでの表示回数や費用のデータが 0 になります。

テスト アカウントと本番用アカウント、アカウントの階層構造の設定に関する詳細については、アカウントを管理するをご覧ください。

設定要素

ここではクライアント ライブラリを使用するため、API 呼び出しが実行される際のバックエンドの仕組みについては詳述しませんが、これらの呼び出しを機能させる SOAP や OAuth2、その他のプロトコルの詳細については、API 呼び出しの仕組みをご覧ください。

クライアント ライブラリを使用する場合でも常に必要となる要素がいくつかあり、上記の手順で設定しましたが、それらの要素についてもう少し詳しく見ていきます。

開発者トークン

開発者トークンは特定のアプリケーションと AdWords API を接続します。本番用 AdWords アカウントで API に接続できるのは承認済みの開発者トークンのみです。承認待ちのトークンではテスト用アカウントにしか接続できません。開発者トークンが承認されたら、そのトークンを使ってご利用のすべての AdWords アカウントに対してリクエストを実行できます。これにはそのトークンに関連付けられている MCC アカウントにリンクされていないアカウントも含みます。

詳細についてはアカウントを管理するをご覧ください。

OAuth2 クライアント ID とクライアント シークレット

クライアント アプリケーションと Google Developers Console のプロジェクトの関連付けと、OAuth2 認証に使用されます。これにより、アカウントの代わりにアプリケーションで各種処理を実行できます。

詳細については、OAuth2 認証をご覧ください。

OAuth2 アクセスとリフレッシュ トークン

API を使用してアプリケーションによる個人データへのアクセスを許可する際は、事前に OAuth2 アクセス トークンを取得して API によるアクセスを許可する必要があります。

クライアント ライブラリを使用する場合は、OAuth2 アクセス トークンが自動的に生成されます。それ以外の方法の詳細については、API 呼び出しの仕組みで API 呼び出しの例をご覧ください。アクセス トークンの生成方法について解説しています。

OAuth2 アクセス トークンは一定期間後に有効期限が切れます。そのためクライアント ライブラリでは、OAuth2 リフレッシュ トークンによって OAuth2 アクセス トークンが自動的に再生成されます。

上記の手順では、クライアント ライブラリのユーティリティによってリフレッシュ トークン生成しています。

OAuth2 と Google API を併用する際の詳細については、OAuth2 認証OAuth2 識別プラットフォームに関するドキュメントをご覧ください。

クライアントのお客様 ID

クライアントのお客様 ID とは、API を介して管理する、AdWords のクライアント アカウントの識別番号のことを指します。通常、形式は 123-456-7890 となります。

クライアントのお客様 ID は、設定ファイルには含めず、プログラムで設定することも可能です。開発者トークンが承認されたら、テスト アカウントではなく本番用アカウントのクライアントのお客様 ID を使用します。

詳細については、サンプルのコードと使用例をご覧ください。

次のステップ

アプリケーションでの最初の API 呼び出しに必要なすべての手順について解説しました。次回のサンプルのコードと使用例では、クライアント ライブラリとサンプルのコードを活用してカスタム レポートや自動化機能を利用する方法について解説します。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。