OAuth2.0について
Yahoo!広告 APIでは、アプリケーションはOAuth2.0による認可を受ける必要があります。認証はYahoo! JAPANビジネスID(以下、「ビジネスID」)を用います。
Yahoo!広告 APIとYahoo!JAPANビジネスIDの関係性
Yahoo!広告では、広告アカウントの参照/登録更新の権限はビジネスID単位で設定を行います。(利用者と権限管理の仕組み)
そのため、ビジネスIDごとに利用できる広告アカウントや実行可能な操作が異なります。
図1 広告アカウント例
Yahoo!広告 APIでも同様に、認可を受けたビジネスIDによって利用できるAPIが異なります。
図2は、ユーザーAから認可を受けた状態です。この場合Yahoo!広告 APIは、広告アカウント①、②の取得、登録、更新削除が実行できます。
図2 ユーザーAから認可を受けた例
ユーザーBから認可を受けてAPIリクエストをする場合、広告アカウント③のみ参照可能です。
レポート、エクスポートなどの一部のServiceを除き、登録更新権限がない場合はget以外はリクエストすることができません。
広告アカウントの参照、登録更新権限が無い状態でAPIリクエストを行うと以下のようなエラーがレスポンスされます。
・HTTP Statusコード:403
・エラーコード:0098
・エラーメッセージ:Permission denied.
ツール管理者から認可を受けると、対象の企業配下の全ての広告アカウントの取得、登録、更新、削除が可能です。
MCCアカウントを用いると、他企業のアカウントでも、権限付与状態であればAPIで操作が可能です。
他企業の広告アカウント連携
図3 他企業の広告アカウント連携例
他企業の広告アカウントを操作する場合、対象の広告アカウントを保有しているビジネスIDから認可を受けることで利用が可能になります。
認可コードフローについて
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コールを実施するをご覧ください。