スタートガイド

このドキュメントは、AdSense Host API を使用して、AdSense アカウントの情報を取得することを目的としたデベロッパーの方を対象としています。このドキュメントは、ウェブ プログラミングの概念やウェブ用のデータ形式について理解していることが前提になっています。

目次

準備

AdSense アカウントを取得する

テストを行うには AdSense アカウントが必要です。テスト アカウントを既にお持ちの場合は、AdSense の管理画面にアクセスしてテストデータの設定、編集、表示を行うことができます。

AdSense について学習する

AdSense の仕組みにまだ詳しくない方は、AdSense の基本情報を参照し、管理画面を試してから、コードの作成を開始してください。

アプリケーションを登録する

AdSense Host API を使用するには、作成するアプリケーションを Google に登録する必要があります。

  1. API コンソールに移動します。
  2. Google アカウントにログインするか、アカウントを作成します。
  3. 新しいプロジェクトを作成します。
  4. 新しく作成したプロジェクトで、AdSense Host API の [アクセスをリクエスト] リンクをクリックします。

OAuth 2.0 アプリケーションの場合は、OAuth 2.0 を使用して Google API にアクセスするに記載されている手順に従ってください。

注: 登録用の Google アカウントにはデベロッパー アカウントを使用する必要があります。つまり、アプリケーションのデベロッパーとして表示するアカウントを使用してください。アプリケーションの使用中、ユーザーには各自のアカウントへのアクセス権が付与されるため、このアカウントを AdSense のログイン情報に関連付ける必要はありません。

AdSense Host API の仕組みを理解する

基本概念

AdSense Host API は、次のようないくつかの AdSense の基本概念に基づいて構築されています。

  • 広告クライアント: 広告クライアントは、AdSense アカウントと、コンテンツ広告や検索広告などの AdSense サービスとの関連付けを表しています。1 つの AdSense アカウントに、複数の広告クライアントを設定することもできます。
  • チャネル: チャネルは特定のページやドメインのパフォーマンスをトラッキングできるツールです。
  • レポート: レポートでは、収益の内容や収益に影響する要因を分析することができます。レポートはアカウント全体のデータに対して作成したり、チャネルを使用して一部の広告枠のデータに絞って作成したりできます。

対応しているオペレーション

この API が現在対応しているオペレーションは、次の表のとおりです。

オペレーション 説明 REST HTTP マッピング
list コレクション内のすべてのリソースをリストします。 コレクション URI に対する GET
get 指定したリソースを取得します。 リソース URI に対する GET
generate 指定したリソースに基づいて結果セットを生成します。レポートでのみ使用できます。 コレクション URI に対する GET/POST。生成の定義としてリソースを渡します。

すべてのオペレーションで認証が必要です。

呼び出しのスタイル

REST は、データのリクエストと変更を一貫した方法で簡単に行うことができるソフトウェア アーキテクチャのスタイルです。

REST は「Representational State Transfer」の略語です。Google API においては、HTTP 動詞を使用して、Google が保存しているデータを取得および変更することを指します。

RESTful システムでは、リソースはデータストアに保存されています。クライアントはサーバーに対して特定のアクション(リソースの作成、取得、更新、削除など)を実行するようリクエストを送信し、サーバーはそのアクションを実行して、多くの場合、指定されたリソースの表現形式でレスポンスを送信します。

Google の RESTful API では、クライアントは POSTGETPUTDELETE などの HTTP 動詞を使用して処理を指定します。リソースの指定には、次のような形式を持つ、グローバルに一意の URI が使用されます。

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

すべての API リソースは固有の HTTP アクセス可能 URI を持っているため、REST はデータ キャッシュが可能で、ウェブの分散インフラストラクチャを利用するよう最適化されます。

REST の詳細については、サードパーティが提供する以下のドキュメントが理解しやすいかもしれません。


AdSense Host API の REST

対応しているオペレーションは REST の HTTP 動詞に直接マッピングされています(詳細は対応しているオペレーションを参照)。

AdSense Host API の URI の形式は次のようになります。

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

ここで、resourceID は広告クライアント、URL チャネル、カスタム チャネル、またはレポート コレクションの識別子、parameters はクエリに適用するパラメータです。

resourceID パス拡張の形式によって、現在操作しているリソースを識別できます。次に例を示します。

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

この API で対応している各オペレーションのすべての URI については、AdSense Host API リファレンスに要約されています。

次の例は、AdSense Host API でどのように機能するかを示しています。

広告クライアントをリストする:

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

データ形式

JSON(JavaScript Object Notation)は言語に依存しない一般的なデータ形式であり、任意のデータ構造を単純なテキスト形式で表示します。詳細については json.org をご覧ください。

リクエストを実行する

リクエストを承認する

アプリケーションが AdSense Host API に送信するリクエストには承認トークンが含まれている必要があります。このトークンは Google でアプリケーションを識別するためにも使用されます。

承認プロトコルについて

リクエストの承認のために、アプリケーションは OAuth 2.0 を使用する必要があります。これ以外の承認プロトコルには対応していません。

OAuth 2.0 によるリクエストの承認

AdSense Host API へのリクエストはすべて、認証されたユーザーによって承認される必要があります。

OAuth 2.0 の承認プロセス(「フロー」)の詳細は、作成するアプリケーションの種類によって多少異なります。次の一般的なプロセスは、すべての種類のアプリケーションに当てはまります。

  1. アプリケーションを作成する際に、Google Developers Console を使用してアプリケーションを登録します。Google から後で必要な情報(クライアント ID やクライアント シークレットなど)が提供されます。
  2. Google Developers Console で AdSense Host API を有効にします(API が Developers Console に表示されない場合は、このステップを省略してください)。
  3. アプリケーションは、ユーザーデータにアクセスする必要がある場合、アクセスの範囲を指定して Google にリクエストします。
  4. Google は同意画面をユーザーに表示して、アプリケーションによる一部のデータのリクエストを承認するかどうかを確認します。
  5. ユーザーが承認した場合、Google はアプリケーションに短期間有効なアクセス トークンを付与します。
  6. アプリケーションは、アクセス トークンをリクエストに付加してユーザーデータをリクエストします。
  7. Google は、リクエストとトークンが有効であると判断した場合、リクエストされたデータを返します。

新しいアクセス トークンを取得するために更新トークンを使用するなど、追加のステップが含まれるフローもあります。さまざまな種類のアプリケーションで使用されるフローの詳細については、Google の OAuth 2.0 に関するドキュメントをご覧ください。

AdSense Host API の OAuth 2.0 の範囲情報は次のようになります。

範囲 意味
https://www.googleapis.com/auth/adsensehost AdSense データに対する読み取り/書き込みアクセス。

OAuth 2.0 を使用してアクセスをリクエストする場合、アプリケーションを登録したときに Google から提供された情報(クライアント ID やクライアント シークレットなど)に加えて、範囲情報が必要になります。

ヒント: Google API クライアント ライブラリは、承認プロセスの一部を処理できます。これらのライブラリはさまざまなプログラミング言語で用意されています。詳細については、ライブラリとサンプルのページをご覧ください。

詳細については OAuth 2.0 セクションをご覧ください。

リクエストを実行する

最後のステップは API リクエストの実行です。クライアント ライブラリを使用しない場合は、参考ドキュメントをご覧ください。

クライアント ライブラリを使用すると、このタスクは非常に簡単です。詳細についてはサンプルとライブラリをご覧ください。Java、Python、PHP、JavaScript クライアント ライブラリで最初のリクエストを実行する方法について説明しています。

OAuth 2.0

AdSense Host API での認証と承認は OAuth 2.0 で処理されます。ただし、AdSense Host の使用モデルにはいくつか特異な点があるため、処理方法が他の Google API とは異なる場合があります。

参加者

OAuth 2.0 リクエストには、次の 3 者が関わります。

  • 個人データへのアクセス権を付与するユーザー
  • アプリケーションを通じてユーザーデータへのアクセス権をリクエストするデベロッパー
  • 関係者の認証と API サービスの提供を受け持つ Google

ただし AdSense Host API の場合、デベロッパーが API を使用して自分の AdSense アカウントとサイト運営者のアカウントへのアクセス権を取得するため、ユーザーとデベロッパーが実際には同一人物となります。

プロジェクトを作成する

新しいプロジェクトは API コンソールのページで作成できます。
図 1: API コンソールの新しいプロジェクト

最初に、使用している他の Google API と同じように、API コンソールで新しいプロジェクトを作成する必要があります。デベロッパー プロジェクトの作成に使用する Google アカウントは、AdSense Host API にアクセスできるようホワイトリストに登録する必要があるため、登録時に用意されたサンドボックス アカウントを使用するか、既に API の導入と公開を済ませている場合は本番用の AdSense アカウントを使用してください。

[サービス] タブでプロジェクトのアクティブな API を選択できます。
図 2: プロジェクトの API の有効化/無効化

Google API プロジェクトの作成方法の詳細については、API コンソールに関するドキュメントをご覧ください。

API アクセスを設定する

プロジェクトを作成したら、OAuth 2.0 クライアント ID を作成して API アクセスを有効化する必要があります。

[API アクセス] タブでは、OAuth 2.0 クライアントを作成できます。
図 3: API コンソールでの新しい OAuth 2.0 クライアントの作成

いくつか方法がありますが、次の手順を簡略化するために、インストール型アプリケーション プロジェクトを作成することをおすすめします。

認証を済ませて永続的に保管する

ご自分の AdSense アカウントを使用して認証を行う必要があります。小さなスクリプトを使用するか、テスト用アプリケーションを使用します(例についてはサンプルコードを参照してください)。

認証を終えたら、認証手続きで取得した更新トークンを忘れずに保管してください。この永続トークンは、アクセス権が明示的に取り消されない限り失効することはありません。ユーザーとして、自分のアプリケーションへのアクセス権を取り消さないようご注意ください。

更新トークンは、今後の認証リクエストのために、アプリケーションのデータストアに保管する必要があります。

保管したトークンをアプリケーションで使用する

更新トークンの入手後は、ウェブサーバー アプリケーション フローで生成された場合でもインストール型アプリケーション フローで生成された場合でも、違いはなくなります。入手した更新トークンを使用して、新しいアクセス トークンの必要性に応じてトークンの更新リクエストを実行できます。Google のクライアント ライブラリを使用する場合は、ドキュメントを参照して独自のトークンを指定する方法をご確認ください。自動生成ファイルまたはデータベースのエントリを編集しなければならない場合もあります。

終了

OAuth 2.0 フローは 1 度だけ実行することになります。以降はサイトのエンドユーザー(サイト運営者)やデベロッパーの方が手動で操作を行わなくても、すべてのリクエストがバックグラウンドで実行されるようになります。

お知らせ

AdSense API のお知らせを通じて、新しいバージョン、新機能、重要なサービス アップデートに関する最新情報を入手してください。

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