アプリのインストール、トークンの生成、更新、取り消し

システムユーザーはサーバー呼び出しを指定するため、Facebookログインを利用できません。そのため、アプリのインストールや、標準Facebook OAuthフローによるトークン生成もできません。これらの操作は、API呼び出しを使って行う必要があります。

システムアクセストークンのタイプ

タイプ	有効期限がないアクセストークン	おすすめの有効期限付きのアクセストークン
有効期間	有効期限なし	60日間有効
更新が必要ですか?	いいえ	はい
ユースケースに基づくおすすめ	リークしたアクセストークンによるリスクを許容し、サードパーティアプリによるデータへのオフラインアクセスを可能にしたい。	リークしたアクセストークンによるリスクを制限したい。

アプリのインストール

アクセストークンの生成に使用するアプリは、システムユーザーまたは管理者システムユーザーがインストールする必要があります。つまり、このシステムユーザーまたは管理者システムユーザーの代わりにアプリがAPIを呼び出せるようにします。

システムユーザーとアプリは、いずれも同じビジネスマネージャに属している必要があります。広告管理APIの標準アクセス以上を持つアプリのみをインストールできます。

システムユーザーに代わってアプリをインストールするには、次が必要です。

access_token: 管理者ユーザー、管理者システムユーザー、別のシステムユーザーのいずれかのアクセストークン
business_app: インストールされているアプリのID

システムユーザーに代わってアプリをインストールするには、次のPOSTリクエストを実行します。

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

インストールが成功すると、この呼び出しでbooleanの結果が返されます。いずれかの条件が満たされていない場合、内容に応じたエラーメッセージが表示されます。

アクセストークンの生成

システムユーザーは、アプリをインストールすると、長期アクセストークンを生成できます。ただし、次のような一部制限があります。

システムユーザーは、上記の手順のとおり、パラメーターで渡されるアプリをインストールしている必要があります。
アプリがターゲットに設定できるのは、それらのアプリを取得したビジネス(またはそれらのビジネスの子ビジネス)のみです。
システムユーザーと、このトークン生成API呼び出しで使用されるアクセストークンの所有者は、同じビジネスマネージャに属している必要があります。
同じビジネスマネージャがアプリを所有している場合と、そうでない場合があります。同じビジネスマネージャが所有していない場合、いくつかの制限があります。下記のセクションをご覧ください。

API呼び出しのパラメーターは以下のとおりです。

business_app: システムユーザーが属するビジネスマネージャが所有するアプリ。
appsecret_proof: アプリの算出されたフィールド。これは、正しいサーバーがAPI呼び出しを実行していることを確認するために必要です。詳しくは、ログインのセキュリティをご確認ください。
scope: 拡張アクセス許可を含む、コンマで区切られた文字列。
access_token: ビジネスマネージャ管理者、管理者システムユーザー、一般システムユーザーのいずれかに属するトークン。
set_token_expires_in_60_days: trueに設定すると、有効期限付きのシステムユーザーアクセストークンが生成される。任意。

システムユーザーに対してサポートされているスコープ:

ads_management
ads_read
business_management
catalog_management
instagram_basic
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
leads_retrieval
manage_notifications
pages_manage_cta
pages_read_engagement
pages_manage_ads
pages_manage_engagement
pages_manage_posts
pages_messaging
pages_show_list
pages_read_user_content
pages_manage_metadata
page_events
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
rsvp_event
whatsapp_business_management
whatsapp_business_messaging

appsecret_proofを生成する場合、次のPHPコードを使うことができます。

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

上記のコードサンプルでは、app_secret_for_the_app_used_in_the_callはアクセストークンの作成に使用されたアプリのapp secretを指します。app secretはアプリダッシュボードで確認できます。

ハッシュ化されたappsecret_proofは"1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3"のような文字列になります。

永続的なシステムユーザーアクセストークンを生成するには、次のようなPOSTリクエストを実行します。

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

有効期限付きのシステムユーザーアクセストークンを生成するには、次のようなPOSTリクエストを実行します。

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

このエンドポイントは、以前は /SYSTEM-USER-ID/ads_access_tokenという名前でした。この名前への呼び出しは無効になりました。

アクセストークンの文字列が返されます。いずれかの条件が満たされていない場合、内容に応じたエラーコードがスローされます。応答は次のようになります。

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

ビジネスマネージャUIを使用してシステムユーザーアクセストークンを生成することもできます。

アクセストークンの更新

有効期限付きのシステムユーザーアクセストークンは、生成日または更新日から60日間有効です。開発者が60日以内にこのアクセストークンを更新すれば、継続させることができます。更新しなかった場合はアクセストークンが消失するので、開発者は新しいアクセストークンを取得して、APIアクセスをもう一度獲得する必要があります。

有効期限付きのシステムユーザーアクセストークンを更新するには、以下が必要です。

fb_exchange_token: 有効なシステムユーザーアクセストークン
client_id: アプリID
client_secret: app secret
set_token_expires_in_60_days: trueに設定すると、有効期限付きのシステムユーザーアクセストークンが更新されます。

GET oauth/access_tokenエンドポイントをクエリします。

リクエストの例

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

応答の例

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

アクセストークンの取り消し

このエンドポイントは、システムを保護する手段として、定期的なトークンのローテーションを実行したり、侵害されたシステムユーザーのアクセストークンを取り消すためのものです。

システムユーザーアクセストークンを取り消すには、以下が必要です。

revoke_token: 取り消すアクセストークン
client_id: アプリID
client_secret: app secret
access_token: 呼び出し元を識別するためのアクセストークン

その要件は以下のとおりです。

client_idは実際のアプリに対応しており、そのアプリは調整、無効化、または削除されていてはなりません。
revoke_tokenのインストール済みアプリ、access_tokenのインストール済みアプリ、client_secretのclient_idは、すべて同じでなければなりません。

GET oauth/revokeエンドポイントをクエリします。

リクエストの例

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

応答の例

{
  "success":"true",
}

アクセストークンのローテーション

トークンのローテーションは、トークンの漏洩による被害を減らすなど、リスクを軽減するのに役立つセキュリティ対策です。アクセストークンを定期的に変更することで、パスワードを変更する場合と同様に、トークンの漏洩や間違った入力で生じ得る損害を少なくすることができます。現在、Metaのシステムでは、ダウンタイムなしのシステムユーザーのローテーションをサポートしています。ローテーションを行うには、次の指示を実行します。

SUAT更新APIを使用してシステムユーザーアクセストークンを更新します。SUAT更新APIは、新しいシステムユーザーアクセストークンを返します。この新しいトークンは更新された日から60日間有効です。古いトークンは、有効期限が切れる(作成日から60日間)まで引き続き使用できます。
新しいシステムユーザーアクセストークンをデプロイします。
SUAT取り消しAPIを使用して、古いシステムユーザーアクセストークンを取り消します。無効化はすぐに行われ、取り消し後にトークンを再度使用することはできません。