Connect Web API

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

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

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

EOS アクセス トークンを要求する

EOS Connect バックエンドは、EOS ゲームサービス Web API のアクセス トークンを要求するための OAuth2.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)>.Example: 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_token, apple_id_token, discord_access_token, epicgames_access_token, epicgames_id_token, gog_encrypted_sessionticket, google_id_token, itchio_jwt, itchio_key, nintendo_id_token, oculus_userid_nonce, openid_access_token, psn_id_token, steam_access_token, steam_encrypted_appticket, xbl_xsts_token

リクエストの例

curl -X "POST" "https://api.epicgames.dev/auth/v1/oauth/token" \ -H "Content-Type:application/x-www-form-urlencoded" \ -H "Accept:application/json" \ -H "Authorization:Basic Q2xpZW50SWQ6Q2xpZW50U2VjcmV0" \ -d "grant_type=client_credentials&deployment_id=<deploymentId>"

トークン レスポンス

HTTP 200 - OK

HTTP ヘッダ

名前

説明

Content-Type

application/json

JSON ペイロード

名前

説明

access_token

JSON Web Token (JWT) 文字列として生成されたアクセス トークン。アクセス トークンは認証済みのクライアントとユーザーを記述します。

token_type

常に bearer に設定されます。

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 Product User ID。 ユーザーアクセストークンに含まれています。

id_token

EOS Product User を安全に識別する ID トークン。ユーザー アクセス トークンに含まれます。

受信した access_token は、Authorization HTTP ヘッダで Bearer トークンとして提供することにより、EOS Game Services Web API を呼び出すために使用されます。例: Authorization:Bearer `.

レスポンスの例

"access_token" : "<Access Token>",
"token_type" : "bearer",
"expires_at" :"2021-06-11T23:10:53.491Z",
"expires_in" :3599,
"features" : ["Matchmaking", "Voice"],
"organization_id" : "<Organization ID>",
"product_id" : "<Product ID>",
"sandbox_id" : "<Sandbox ID>",
"deployment_id" : "<Deployment ID>"

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

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

ポリシー

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

認証

この呼び出しは、EOS クライアント トークンを使って Bearer トークン認証を要求します。

QueryExternalAccounts リクエスト

HTTP リクエスト

GET /user/v1/accounts

HTTP ヘッダ

名前

説明

Authorization

Bearer <EOS クライアント アクセス トークン>

HTTP クエリ パラメータ

名前

説明

accountId

配列 <String>

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

identityProviderId

文字列

サポートされている ID プロバイダー 使用可能な値: Amazon, apple, discord, epicgames, gog, google, itchio, nintendo, oculus, Openid, psn, steam, xb

environment

文字列

外部アカウント システムが分離されたアカウント環境を使用する場合は、環境を指定する必要があります。使用可能な環境値については、プラットフォーム プロバイダのドキュメントを参照してください。それ以外の場合、フィールドを排除しなければなりません。

リクエストの例

curl -X "GET" "https://api.epicgames.dev/user/v1/accounts?accountId=<ExternalAccountId_1>&accountId=<ExternalAccountId_2>&identityProviderId=<IdentityProviderId>" \ -H "Accept:application/json" \ -H "Authorization:Bearer <EOS client access token>"

QueryExternalAccounts レスポンス

HTTP Response 200 - OK:Success.

HTTP ヘッダ

名前

説明

Content-Type

application/json

JSON ペイロード

名前

説明

ids

オブジェクト <String, String> キーは外部アカウント ID です。値は製品ユーザー ID です。

外部アカウント ID を製品ユーザー ID にマッピングするオブジェクト。外部アカウント ID が製品ユーザー ID に関連づけられていない場合、レスポンスから除外されます。

レスポンスの例

    {
        "ids": {
            "<ExternalAccountId_1>": "<ProductUserId_1>",
            "<ExternalAccountId_2>": "<ProductUserId_2>",
        }
    }

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

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

ポリシー

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

認証

この呼び出しは、EOS クライアント トークンを使って Bearer トークン認証を要求します。

QueryProductUsers Request

HTTP Request

GET /user/v1/product-users

HTTP Headers

Name

Value

Authorization

Bearer <EOS client access token>

HTTP Query Parameters

Name

Type

Description

productUserId

Array <String>

A list of Product User IDs to query accounts for.The maximum number of input Product User IDs is 16.

リクエストの例

    curl -X "GET" "https://api.epicgames.dev/user/v1/product-users?productUserId=<ProductUserId_1>&productUserId=<ProductUserId_2>" \
    -H "Accept:application/json" \
    -H "Authorization:Bearer <EOS client access token>"

QueryProductUsers Response

HTTP Response 200 - OK:Success.

HTTP Headers

Name

Value

Content-Type

application/json

JSON Payload

Name

Type

Description

productUsers

Object <String, ProductUser> Key is a Product User ID.

Object that maps Product User IDs to accounts.If the Product User ID is not found, it will be excluded from the response.

Schema

ProductUser

Name

Type

Description

accounts

Array<Account>

Accounts associated with the Product User.

Account

Name

Type

Description

accountId

String

External Account ID.

identityProviderId

String

Identity provider of the external account.

Supported providers are:

  • amazon

  • apple

  • discord

  • epicgames

  • gog

  • google

  • itchio

  • nintendo

  • oculus

  • openid

  • psn

  • steam

  • xbl

New identity providers may be added to the list.

displayName

String (optional)

Display name of the user.

lastLogin

String

Last login time, ISO 8601.

Example Response

    {
        "productUsers": {
            "<ProductUserId_1>": {
                "accounts": [
                    {
                        "accountId": <AccountId_1>",
                        "displayName": "<DisplayName_1>",
                        "identityProviderId": "<IdentityProvider_1>",
                        "lastLogin":"2022-03-18T11:55:44Z"
                    }
                ]
            },
            "<ProductUserId_2>": {
                "accounts": [
                    {
                        "accountId": <AccountId_2>",
                        "displayName": "<DisplayName_2>",
                        "identityProviderId": "<IdentityProvider_2>",
                        "lastLogin":"2022-01-05T10:25:38Z"
                    }
                ]
            }
        }
    }