認可認証について

Yahoo!広告 APIで広告アカウントのデータを操作するためには、アプリケーションはOAuth2.0による認可を受ける必要があります。
認証はYahoo! JAPANビジネスID(以下、「ビジネスID」)を用います。ビジネスIDで認証することで、ビジネスIDが権限を持つ広告アカウントのデータをアプリケーションで操作できるようになります。

概要

ここでは、Yahoo! 広告APIで広告アカウントのデータを操作するための認可認証について説明しています。

・Yahoo!広告 APIとYahoo!JAPANビジネスIDの関係性

・認可コードフローについて

Yahoo!広告 APIとYahoo!JAPANビジネスIDの関係性

Yahoo!広告では、広告アカウントの参照/登録更新の権限はビジネスID単位で設定を行います。(権限管理機能とは)
そのため、ビジネスIDごとに利用できる広告アカウントや実行可能な操作が異なります。

  図1 広告アカウント例

Yahoo!広告 APIでも同様に、認可を受けたビジネスIDによって利用できる広告アカウントが異なります。

図2は、ユーザーAから認可を受けた状態です。ユーザーAはMCCアカウント2、広告アカウント1、2の登録更新権限を持っているので、この場合Yahoo!広告 APIで認可を受けたトークンを利用し、ベースアカウントにMCCアカウント2を指定したアプリケーションAは、広告アカウント1、2の取得、登録、更新削除が実行できます。

  図2 ユーザーAから認可を受けた例

ユーザーBから認可を受けてAPIリクエストをする場合、ユーザーBは広告アカウント3の参照権限のみしか持っていないので、ベースアカウントに広告アカウント3を指定すると、広告アカウント3のみ参照可能となります。
レポート、エクスポートなどの一部のServiceを除き、参照権限のみの場合(登録更新権限がない場合 )get以外はリクエストすることができません。
広告アカウントの参照、登録更新権限が無い状態でAPIリクエストを行うと以下のようなエラーがレスポンスされます。

  ・HTTP Statusコード:403
  ・エラーコード:0098
  ・エラーメッセージ:Permission denied.

Yahoo! 広告のツール管理権限を持つビジネスIDから認可を受けると、ベースアカウントにルートMCCを指定することで、対象の企業配下の全ての広告アカウントの取得、登録、更新、削除が可能です。
具体的なパターンごとの認証については、「はじめに」をご確認ください。

認可コードフローについて

Yahoo!広告 APIのOAuth2.0は認可コードフローのみを提供し、それ以外の認可フローはご利用いただけません。認可コードフローは図4にて表されます。

  

  図4 認可コードフロー

広告主/代理店の場合は「ユーザー」と「アプリケーション」がそれぞれ自社の従業員、Yahoo!広告 API契約企業の自社システムとなります。
ツールプロバイダーの場合、「アプリケーション」はYahoo!広告 APIを使用している自社システムですが、「ユーザー」はデータ取得先の広告アカウントのYahoo! JAPANビジネスIDを持った広告主/代理店(他社)になります。

認可、アクセストークンの取得の手順は以下のとおりです。

1. ユーザーがYahoo!広告を利用開始すると、アプリケーションは認可サーバー(/oauth/v1/authorize)にブラウザで認可リクエストを送ります。
2. 認可サーバーは認可リクエストを受け取ると「Yahoo! JAPANビジネスIDログイン画面」へリダイレクトします。
3. ユーザーは「Yahoo! JAPANビジネスIDログイン画面」でYahoo! JAPANビジネスIDを使ってログインします。
4. ログインが成功するとアプリケーションの認可を承認する画面が返ります。
5. ユーザーがアプリケーションの認可を承認すると、アプリケーション登録時に設定したリダイレクトURIにリダイレクトされます。
6. 認可コードを認可サーバー(/oauth/v1/token)に送ることでアクセストークンを取得できます。また、このときリフレッシュトークンも返ってきます。
7. 取得したアクセストークンでYahoo!広告 APIにAPIリクエストを送ります。

初回のアクセストークンを取得し、認可されていれば、6で取得したリフレッシュトークンを使ってアクセストークンを再取得することができます。

詳細なAPIコールの手順はAPIコールを実施するをご覧ください。