Connect Web APIs

Connect インターフェース Web API を使用して、EOS ゲーム サービスの Web API で認証を行います。

7 分で読めます

EOS ゲーム サービスには、リクエストを行う認証済みのクライアントを特定するためにアクセス トークンを必要とする Web API を使用してアクセスできます。クライアントは、個別のクライアントとして (クライアント アクセス トークン)、またはユーザーに代わって (ユーザー アクセス トークン) アクセス トークンをリクエストできます。

たとえば、Web アプリケーションは、プレイヤーにアカウントリンク管理機能を提供するためにユーザーを認証することがあります。個別のクライアントは、EOS Voice バックエンド サービスでホストされる音声チャット ルームを調整する、パブリッシャーホスト型のバックエンドになる場合があります。

EOS アクセス トークンをリクエストする

EOS Connect バックエンドは、EOS ゲーム サービスの Web API のアクセス トークンをリクエストするための OAuth 2.0 トークン エンドポイントを提供します。

EOS Connect トークン エンドポイントは次のとおりです。

https://api.epicgames.dev/auth/v1/oauth/token

クライアントは、次の 2 種類のアクセス トークンをリクエストできます。

  • クライアント アクセス トークン:一般製品レベルのアクセスのためにバックエンド サービスとやり取りする個別のクライアントで使用されます。
  • ユーザー アクセス トークン:認証済みのユーザーに代わってバックエンド サービスとやり取りするクライアントで使用されます。

クライアントがアクセス トークンをリクエストするときには、製品の有効なクライアント資格情報を提示する必要があります。デベロッパー ポータル[Product Settings (製品設定)] で各 製品クライアント を作成し、個別のクライアントのポリシーを受け取ることができます。

クライアントは、次の 2 つの方法のいずれかでクライアント資格情報を渡すことができます。

  • 標準の Authorization HTTP ヘッダを使用する。
  • POST パラメータを使用する。

トークン リクエスト

HTTP リクエスト POST /auth/v1/oauth/token
HTTP ヘッダ
名前
Authorization Basic <Base64(ClientId:ClientSecret)>Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0
Content-Type application/x-www-form-urlencoded
POST ボディ パラメータ
名前説明
grant_type クライアント アクセスの場合は client_credentials を使用します。ユーザー アクセスの場合は external_auth を使用します。
client_id クライアント資格情報 ID。Authorization HTTP ヘッダが使用されていない場合は必要です。
client_secret クライアント資格情報シークレット。Authorization HTTP ヘッダが使用されていない場合は必要です。
nonce セキュリティを強化するクライアントが指定した任意の文字列値。正しいノンス値であることを確認するためにクライアントの API レスポンスに含められます。ユーザー アクセスの場合は必要です。
deployment_id 必須のユーザー アクセスのアクセスをリクエストするためのターゲット EOS デプロイメント。
external_auth_token 外部アカウント システムのユーザー アカウントを識別する外部認証トークン。ユーザー アクセスの場合は必要です。
external_auth_type 外部認証トークンのタイプを識別します。ユーザー アクセスの場合は必要です。使用可能な値は次のとおりです。amazon_access_tokenapple_id_tokendiscord_access_tokenepicgames_access_tokenepicgames_id_tokengog_encrypted_sessionticketgoogle_id_tokenitchio_jwtitchio_keynintendo_id_tokenoculus_userid_nonceopenid_access_tokenpsn_id_tokensteam_access_tokensteam_encrypted_appticketxbl_xsts_token

リクエストの例

トークン レスポンス

HTTP Response 200 - OK:Success.
HTTP ヘッダ
名前
Content-Type application/json
JSON ペイロード
名前説明
access_token JSON Web トークン (JWT) の文字列として生成されたアクセス トークン。このアクセス トークンは、認証済みのクライアントとユーザーを示します。
expires_at トークンの有効期限。Unix エポックからの経過秒数を示す NumericDate の数値が含まれます。
expires_in トークンの存続期間。トークンの発行時刻から期限切れまでの秒数。
nonce トークン リクエストでクライアントが指定した任意の文字列型の値。セキュリティを強化するためにクライアントで使用されます。HTTP レスポンスでアクセス トークンを受け取ると、クライアントはトークン レスポンスに期待どおりのノンス値が含まれていることを確認できます。
organization_id 組織の識別子。
product_id 製品の識別子。
sandbox_id サンドボックスの識別子。
deployment_id デプロイメントの識別子。
features クライアントがアクセスできる機能のリスト。クライアントの機能はデベロッパー ポータルで有効にできます。
organization_user_id 組織内の製品の EOS ユーザーを一意に識別します。ユーザー アクセス トークンに含められます。
product_user_id 認証済み EOS 製品ユーザー ID。ユーザー アクセス トークンに含められます。
id_token EOS 製品ユーザーをセキュアに識別する ID トークン。ユーザー アクセス トークンに含められます。

受け取った access_token は、Authorization HTTP ヘッダでベアラー トークンとして指定することにより、EOS ゲーム サービスの Web API の呼び出しに使用されます。たとえば、Authorization:Bearer <access_token> のようになります。

レスポンスの例

外部アカウントをクエリする

リクエスト queryExternalAccountsForAnyUser は、外部アカウント ID のリストから関連する製品ユーザー ID を返します。

ポリシー

クライアントは、Connect 機能に対して queryExternalAccountsForAnyUser クライアント ポリシー アクションを有効にする必要があります。

認証

この呼び出しには、EOS クライアント アクセス トークンを使用したベアラー トークン認証が必要です。

QueryExternalAccounts リクエスト

製品ユーザー ID をクエリする外部アカウント ID のリスト。入力可能なアカウント ID の最大数は 16 です。

HTTP リクエスト GET /user/v1/accounts
HTTP ヘッダ
名前
Authorization Bearer <EOS client access token>
HTTP クエリ パラメータ
名前説明
accountId 配列<String>
identityProviderId 文字列 サポートされる ID プロバイダ。使用可能な値は次のとおりです。AmazonapplediscordepicgamesgoggoogleitchionintendooculusOpenidpsnsteamxbl
environment 文字列 外部アカウント システムで分離されたアカウント環境が使用される場合は、環境を指定する必要があります。使用可能な環境の値については、プラットフォーム プロバイダのドキュメントを参照してください。指定しない場合はこのフィールドを除外する必要があります。

リクエストの例

QueryExternalAccounts レスポンス

HTTP Response 200 - OK:Success.
HTTP ヘッダ
名前
Content-Type application/json
JSON ペイロード
名前説明
ids オブジェクト <String, String> 外部アカウント ID を製品ユーザー ID にマッピングするオブジェクト。キーは外部アカウント ID です。外部アカウント ID が製品ユーザー ID と関連付けられていない場合、その外部アカウント ID はレスポンスから除外されます。

レスポンスの例

製品ユーザーをクエリする

リクエスト queryProductUsersForAnyUser は、製品ユーザー ID のリストから関連するアカウントを返します。

ポリシー

クライアントは、Connect 機能に対して queryProductUsersForAnyUser クライアント ポリシー アクションを有効にする必要があります。

認証

この呼び出しには、EOS クライアント アクセス トークンを使用したベアラー トークン認証が必要です。

QueryProductUsers リクエスト

HTTP リクエスト GET /user/v1/product-users
HTTP ヘッダ
名前名前
Authorization Bearer <EOS client access token>
HTTP クエリ パラメータ
名前説明
productUserId 配列 <String> アカウントをクエリする製品ユーザー ID のリスト。入力可能な製品ユーザー ID の最大数は 16 です。

リクエストの例

QueryProductUsers レスポンス

HTTP Response 200 - OK:Success.
HTTP ヘッダ
名前
Content-Type application/json
JSON ペイロード
名前説明
productUsers オブジェクト <String, ProductUser>

製品ユーザー ID をアカウントにマッピングするオブジェクト。キーは製品ユーザー ID です。製品ユーザー ID が見つからない場合、その ID はレスポンスから除外されます。

ProductUser スキーマ

ProductUser
名前説明
accounts 配列<Account> 製品ユーザーと関連付けられているアカウント。

アカウント スキーマ

アカウント
名前説明
accountId 文字列 外部アカウント ID。
identityProviderId 文字列

外部アカウントの ID プロバイダ。新しい ID プロバイダが追加される場合があります。 これは、サポートされているプロバイダーのデフォルト リストです:

  • amazon
  • apple
  • discord
  • epicgames
  • gog
  • google
  • itchio
  • nintendo
  • oculus
  • openid
  • psn
  • steam
  • xbl
displayName 文字列 (任意) ユーザーの表示名。
lastLogin 文字列 ISO 8601 に基づく最終ログイン時刻。

レスポンスの例