はじめる

概要

エクソーラAPIは以下のことを含む:

エクソーラAPIはRESTに基づいて設計されています。APIには、予測可能なリソース指向のURLがあり、HTTPレスポンスコードを使用してAPIエラーを示します。APIは、エラーの場合を含め、常にJSON形式で応答します。

APIは、HTTP認証やHTTP動詞などの組み込みのHTTP機能を使用します。これは、既製のHTTPクライアントによって解釈できます。また、クロスオリジンリソースシェアリングをサポートしているため、クライアントWebアプリケーションから安全にアクセスできます。

エクソラAPIは次のエンドポイントのパスを使います:
  • https://api.xsolla.com — ペイステーションAPI、アドミンページAPI、サブスクリプションAPI
  • https://login.xsolla.com/api — ログインAPI
  • https://store.xsolla.com/api — インゲームストア&ゲームキーの直接販売API
ほとんどのエンドポイントのパスには、merchant_idパラメーターが含まれています。これは、アプリケーションが出品者のために機能していることを示します。

リクエストとレスポンス

エクソーラAPIのリクエストに必要なこと:
  • HTTPSで送信。
  • TLS 1.2以降を使用。
  • 認証パラメータを含める。
  • 追加ヘッダーContent-Type: application/jsonをPUTリクエストとPOSTリクエストに含める。
Copy
Full screen
Small screen
    Authorization: Basic <your_authorization_basic_key>
    Content-Type: application/json
    

    既定では、すべてのリクエストが本文にJSONデータを持ち、Content-Type: application/jsonヘッダーを含むレスポンスを返します。

    APIの変更内容

    エクソーラはAPIの機能を次のように変更することがあります:
    • 新しいAPIリソースを追加する。
    • オプションのリクエストパラメータを追加する。
    • 既存のAPIレスポンスに新しいプロパティを追加する。
    • 列挙可能な値の既存のパラメータに新しい値を追加する。
    • 新しいウェブフックタイプとJSONパラメータを追加する。
    • HTTPリクエストヘッダを追加する。
    • 有効なパラメータに無効な値が含まれているリクエストを拒否する。
    • 解析ロジックが変更された場合、寛大な構文解析のために以前に受け入れられた不適切な形式のリクエストを拒否する。
    • 文書化されていない機能をいつでも追加、変更、削除することができる。
    変更に関係なく、クライアントは機能し続けます。たとえば、クライアントによって認識されない新しいJSONパラメータは、通常の操作を妨げてはいけません。

    バージョン管理

    すべてのエクソーラAPIメソッドはバージョン管理をサポートしています。現在のバージョンと互換性のない変更があるたびに新しいバージョンを発行します。バージョンは、URLの"/merchant"接頭辞に続く"v1"や"v2"などの識別子によって識別されます。 初めてAPIを使用する場合は、最新のバージョンを使用してください。バージョンを省略すると、デフォルトで最初のバージョンが使用されます。
    お知らせ
    エクソラでは、同じバージョン内でのみAPIの完全性を保証することができます。

    認証

    エクソーラAPIは基本アクセス認証を採用しています。APIに対する全リクエストは、Authorization: Basic <your_authorization_basic_key>ヘッダーを含む必要があります。<your_authorization_basic_key>マーチャントID:APIキーのペアで、Base64の基準に従ってエンコードしています。アドミンページに移動して、次のパラメータを見つけます:
    • マーチャントIDは以下の場所で表示されます:
      • プロジェクト設定 > ウェブフックセクション。
      • 会社設定 > 会社セクション。
      • アドミンページページのブラウザーアドレスバーのURL。URLは以下の形式があります:`https://publisher.xsolla.com/​マーチャントID/アドミンページセクション`。
    • APIキーは、作成時に一度だけアドミンページに表示され、お客様側で保存する必要があります。次のセクションで新しいキーを作成できます:
      • 会社設定 > APIキー
      • プロジェクト設定 > APIキー
    注意

    APIキーの操作については、APIリファレンスを参照してください。

    キーに関する推奨事項:

    • 生成されたAPIキーは、お客様側で保存してください。APIキーは、アドミンページで作成時に一度だけ表示することができます。
    • APIキーは秘密にしておいてください。APIキーは、お客様の個人アカウントとアドミンページのプロジェクトへのアクセスを提供します。
    • APIキーはサーバーに保存する必要があり、決してバイナリやフロントエンドに保存してはいけません。

    エンドポイントの種類

    エンドポイントのタイプは、どのような種類のデータを処理するのか、どのような処理を実行するのかを示します。最も一般的なアクションは次のとおりです。
    アクションHTTPメソッド説明文
    作成POST指定されたタイプのエンティティを作成して保存します。
    リストGETクエリに一致するエンティティのリストを返します。エンティティの詳細を取得するには、最初に対応するリストのエンドポイントを使用してそのIDを見つけ、このIDを対応する取得のエンドポイントに提供します。
    取得GET指定されたIDを持つエンティティの詳細を提供します。
    置換PUT指定されたIDを持つエンティティのすべてのフィールドを変更します。
    更新PATCH指定されたIDを持つエンティティの指定されたフィールドを変更します。
    削除DELETE指定されたIDを持つエンティティを削除します。

    日付形式

    すべての日付は、ISO 8601に従って文字配列として指定されます。日付文字配列は、UTC(例:2013-01-15T00:00:00Z)、またはUTCオフセット(例えばUTC+8の場合、2013-01-15T00:00:00-08:00)を指定できます。後者の場合は、夏時間を考慮してください。

    ページネーション

    リストのエンドポイントは、返された結果にページ区切りを付けることがあります。つまり、すべての結果を単一のレスポンスで返す代わりに、これらのエンドポイントは結果の一部と、次の結果セットにリンクするレスポンスヘッダを返す可能性があります。この目的のために、offsetトlimitのパラメータを使用します。

    エラー処理

    サポートされているHTTPエラーの一覧:
    • 200、201、204-エラーはありません。
    • 400 Bad Request-これは必要なパラメーターが欠落していることを示します。詳細については、レスポンス本文を参照してください。
    • 401 Unauthorized-有効なAPIキーがありません。
    • 402 Request Failed-パラメータは有効でしたがリクエストの実行に失敗しました。
    • 403 Forbidden-許可されていません。詳細については、レスポンス本文を参照してください。
    • 404 Not Found-要求された項目が見つかりません。
    • 409、422-リクエストパラメータが無効です。
    • 412 Precondition Failed —プロジェクトはまだアクティブ化されていません(トークンを作成するメソッドで使用されています)。
    • 415 Unsupported Media Type-HTTPヘッダに Content-Type: application/jsonがありません。
    • 500、502、503、504 Server Errors-サーバーエラーが起きました。
    エクソーラは、従来のHTTPレスポンスコードを使用して、APIリクエストが成功したかどうかを示します。一般的に、2xxは成功を示し、4xxは提供された情報のエラー(例えば、必要なパラメータの欠落、認証の失敗など)を示し、5xxはエクソーラのサーバに関する問題を示します。 しかし、すべてのエラーがHTTPレスポンスコードと完全に一致するわけではありません。たとえば、リクエストが有効であったにもかかわらず失敗した場合、APIは422エラーコードを返します。 すべてのAPIエラーレスポンスは、JSONオブジェクトに次のフィールドを提供します。
    名前種類説明文
    http_status_codeintegerHTTPコード。
    messagestring人間が判読できるエラーの説明。このメッセージは常に英語で表示されます。将来的に変更される可能性があるため、特定のエラーのためにこの値に頼らないでください。
    extended_messagestringより詳細なエラーの説明。
    request_idstringトラブルシューティングに使用する固有のリクエストID。
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }
    

    レート制限

    一般情報

    エクソーラシステムの過負荷を回避し、受信トラフィックのバーストからシステムを保護するために、エクソーラは、指定された期間内に エクソーラAPIによって受信されるリクエストの数を制限します。制限を超えた場合、エクソーラAPIは429ステータスコードでHTTPレスポンスを返します。 制限値は、方式、プロジェクト、その他の要因によって異なります。現在の制限値は、エクソーラシステムの安定的かつ継続的な運用を保証するために定期的に更新されます。場合によっては、事前のリクエストにより、指定された制限を調整することが可能です。カスタマーサクセスマネージャーに連絡するか、メールcsm@xsolla.comまでリクエストを送信してください。

    レート制限を超える一般的な原因

    • パートナー側のトラフィックが急激に増加した原因は以下通り:
      • 季節セール
      • クローズドテストとオープンテストの開始
    • パートナー側でのDDoS攻撃の結果、トラフィックが急激に増加しました。
    • 不適切に構成された統合。例:
      • Catalogサブセクションのメソッドの代わりに、頻繁に使用することに対応していないAdminサブセクションのメソッドを使用すること
      • 注文の状態とその中のアイテムのリストを取得するために、Get orderメソッドを頻繁に呼び出すこと。例:推奨されるリクエストの遅延時間は3秒ですが、1秒に1回呼び出されます
    • 一定時間内に過剰に多くのリクエストを起動すること。例:アイテムカタログを表示するためのGet virtual items listメソッドを1秒間に200回以上呼び出すこと。

    レート制限の処理

    レート制限によるエラーを防ぐために、以下のことをお勧めします:
    • 429ステータスコードを追跡し、再試行メカニズムを作成します。連続再試行の代わりに、再試行間に固定または指数バックオフを持つ再試行パターンを使用することができます。
    • 必要なデータのみを取得するようにコードを最適化します。アプリケーションが必要とするリクエストのみを行い、不要なAPIコールを避けるようにします。インゲームストア&ゲームキーの直接販売APIを使用している場合は、WebSocket APIを使用することで呼び出し回数を減らすことができます。
    • アプリケーションで頻繁に使用されるデータをキャッシュします。静的なデータを手元に置いて、外部APIへのリクエストの数を減らすことができます。
    • APIを破壊するDDoS攻撃を防ぐことができます。
    • リクエストのレートを調整することで、よりスムーズな配信が可能になります。429エラーが定期的に発生する場合は、リクエストのレートを調節し、リクエストをより均等に分散できるようなプロセスをコードに含めることを検討してください。

    APIキー

    APIキーは、ユーザーデータの暗号化およびAPIリクエストの認証に使用される一意のキーです。アドミンページでは、会社のすべてのプロジェクトと個々のプロジェクトに対してAPIキーを作成できます。

    お知らせ
    全社のプロジェクトで有効なAPIキーは、個々のプロジェクトのページには表示されません。
    注意

    以下のロールのいずれかに該当する場合、APIキーの操作(リストを表示、作成、または削除する)が可能です:

    • 開発者
    • 所有者

    会社設定 > ユーザーセクションのアドミンページでロールを変更できるのは、プロジェクト所有者のみです。

    APIキーを作成する

    APIキーを作成するには:
    1. アドミンページを開きます。
    2. 会社設定 > APIキーまたはプロジェクト設定 > APIキーセクションに移動します。
    3. APIキーを作成するをクリックします。
    4. 以下のフィルドを入力します:
      • キーのリストに表示されるキーの名前。キーを簡単に識別できるような名前を設定します。
      • キーのタイプ — 永久的または一時的。
      • 有効期限 — 一時的なキーの場合のみです。有効期限を過ぎると、そのキーは無効となり、新たにキーを作成する必要があります。
      • キーが有効なプロジェクト(プロジェクトページでAPIキーを作成しても、このフィールドは表示されません)。デフォルトでは、すべてのプロジェクトが選択されています。
    5. 作成するをクリックします。
    6. 開いたウィンドウで、APIキーをコピーするをクリックし、作成したAPIキーを自分側で保存します。
    お知らせ
    プロジェクトページでAPIキーを作成した場合、そのキーはこの特定のプロジェクト内のみで有効です。
    注意
    キーに関する推奨事項:
    • 生成されたAPIキーは、お客様側で保存してください。APIキーは、アドミンページで作成時に一度だけ表示することができます。
    • APIキーは秘密にしておいてください。APIキーは、お客様の個人アカウントとアドミンページのプロジェクトへのアクセスを提供します。
    • APIキーはサーバーに保存する必要があり、決してバイナリやフロントエンドに保存してはいけません。

    APIキーを削除する

    APIキーを削除するには:
    1. アドミンページを開きます。
    2. 会社設定 > APIキーまたはプロジェクト設定 > APIキーセクションに移動します。
    3. APIキーの行で、ビンのアイコンをクリックし、動作を確認します。
    以下の場合、APIキーの削除が中止されます:
    • このAPIキーが使われたプロジェクトで支払いを受ける
    • このAPIキーを使用したAPIメソッドを呼び出す
    それを防ぐには:
    1. 新しいAPIキーを作成します
    2. 新しいAPIキーを使用するようにアプリケーションを変更します。
    3. 初期のAPIキーを削除します。

    ウェブフック

    ウェブフックを使用すると、エクソーラ側で構成されたイベントの即時通知を受信できます。処理用エクソーラを設定することで、アプリケーションを自動化することができます。利用可能なウェブフックのリストとその動作の詳細については、当社のドキュメンテーションを参照してください。

    この記事は役に立ちましたか?
    ありがとうございます!
    改善できることはありますか? メッセージ
    申し訳ありません
    この記事が参考にならなかった理由を説明してください。 メッセージ
    ご意見ありがとうございました!
    あなたのメッセージを確認し、体験を向上させるために利用させていただきます。
    このページを評価する
    このページを評価する
    改善できることはありますか?

    答えたくない

    ご意見ありがとうございました!
    最終更新日: 2024年1月24日

    誤字脱字などのテキストエラーを見つけましたか? テキストを選択し、Ctrl+Enterを押します。