API v2 の概要ベータ
v2 名前空間の API の動作について説明します。
Stripe API は、異なるエンドポイントが含まれる 2 つの名前空間を提供しています。
- API v1:
/v1
名前空間には、現在既存の Stripe API の大部分が含まれています。 - API v2: The
/v2
namespace includes endpoints that use/v2
design patterns.
v1 と v2 の名前空間の主な違い
API v1 | API v2 | |
---|---|---|
API キー | Use secret and restricted access keys to access APIs in the /v1 namespace. | You can only access APIs in the /v2 namespace with secret keys. |
リクエストのペイロード | フォームのエンコード方式 (application/x-www-form-urlencoded )。 | JSON のエンコード方式 (application/json )。 |
API のテスト | Validate APIs in the | Validate APIs in the もっと読む: サンドボックス |
べき等 |
|
もっと知る: べき等 |
イベント | Webhook エンドポイントは、API v1 リソースによって生成されたイベントのみに対応します。イベントには、ペイロードの API オブジェクトのスナップショットが含まれます。 | Event destinations support events generated by API v1 and API v2 resources. Events for API v2 resources only include a minimal, unversioned push payload (see thin events). もっと読む: イベントの送信先 |
リストのページ分割 | List API リクエストの先頭のエレメントとしてオブジェクトの ID を指定します。API レスポンスの | Specify the もっと知る: リストのページ分割 |
リストの一貫性の保証 | 上位のリストはすぐに一貫したものになります (表示されるまでの待ち時間は長くなります)。一部のサブリストは最終的には一貫したものになります。 | リストはデフォルトで最終的に一貫したものになり、低遅延になります。 |
オブジェクトの拡張 |
もっと読む: レスポンスの拡張 |
|
包含 | include パラメーターはサポートされていません。 | この名前空間の一部の API は、include パラメーターを使用して API レスポンスで追加のフィールドを提供する場合があります。 |
メタデータ | 値を空の文字列に設定して、キーと値のペアを削除します。 | 値を null に設定して、キーと値のペアを削除します。 |
API v2 をサポートする SDK
以下の言語のベータ SDK は、/v2
名前空間の API をサポートしています。
Use an SDK if one is available for your language.
Stripe CLI で API v2 を使用する
Use stripe trigger
and stripe listen
to test your integration’s event handling. You can’t access APIs in the /v2
namespace using the Stripe CLI.
SDK、CLI、API のバージョン管理
SDK と Stripe CLI には、すべてのリクエストの API バージョンが自動的に含まれます。SDK または CLI のバージョンを更新すると、Stripe は、リクエストとレスポンスの API バージョンを同時に更新します。
Include the Stripe-Version when not using an SDK or the CLI
API /v2
名前空間に対する API リクエストのすべてに Stripe-Version
ヘッダーを含め、基礎となる API バージョンを指定する必要があります。
For example, a curl request using API version 2024-08-16.
looks like:
curl https://api.stripe.com/v2/events \ -H "Authorization: Bearer {{YOUR_API_KEY}}" \ -H "Stripe-Version: 2024-08-16.preview-v2" \ -H "Content-Type: application/json" \ -d <JSON request body>
v1 と v2 の名前空間の API を、同じシステムで使用する
You can use any combination of APIs in the /v1
or /v2
namespace in the same integration.
公式の SDK または CLI を使用していない場合は、必ず、API コールの URL パスに名前空間を含めてください。以下に例を示します。
# Call a v2 API curl https://api.stripe.com/v2/events?related_object=mtr_1234 # Call a v1 API curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd
リストのページ分割
List APIs in the /v2
namespace (for example, GET /v2/events
) include a different interface to paginate through lists than the /v1
namespace:
- The
previous_
property returns a URL to fetch the previous page of the list. If there are no previous pages, the value ispage null
. - The
next_
property returns a URL to fetch the next page of the list. If there are no more pages, the value ispage null
.
You can’t change list filters after the first request.
べき等
/v2
名前空間の API では、べき等の動作に対するサポートが改善されており、同じべき等キーを使用してリクエストが複数回実行されたときの想定外の副次的影響は防止されます。API が、同じべき等キーを使用する 2 つのリクエストを受信すると、以下のようになります。
- If the first request succeeded, the API skips making new changes and returns an updated response.
- If the first request failed (or partially failed), the API re-executes the failed request(s) and returns the new response.
- まれに、べき等の再生が成功しなくなった場合、API は、理由を説明するエラーを返します。
以下のすべてが該当する場合、2 つのリクエストはべき等と見なされます。
- Use the same idempotency key for the same API
- Occur in the scope of the same account or sandbox
- 互いに過去 30 日以内に発生する
べき等キーを指定するには、Idempotency-Key
ヘッダーを使用して、操作を表す一意の値 (UUID を推奨) を指定します。キーが指定されない場合、Stripe は UUID を自動的に生成します。
POST
と DELETE
の API v2 リクエストはすべて、べき等キーを受け入れ、べき等を利用して動作します。GET
リクエストは、定義により、べき等性を備えているため、べき等キーを送信しても効果はありません。
API v1 と API v2 のべき等の違い
API v1 と API v2 のべき等には、大きな違いがいくつかあります。
- API v1 は、
POST
リクエストでのみ、べき等の再生をサポートしています。API v2 は、すべてのPOST
リクエストとDELETE
リクエストをサポートしています。 - Two requests are considered idempotent for:
- API v1 if they use the same idempotency key and occur within 24 hours of each other.
- API v2 if they use the same idempotency key, are made to the same API, occur within the scope of the account or sandbox, and are made within 30 days of each other.
- When you provide the same idempotency key for two requests:
- API v1 always returns the previously-saved response of the first API request, even if it was an error.
- API v2 は、副次的作用 (API コールの結果として発生する外部の変更または観測可能な動作) を発生させることなく、失敗したリクエストを再試行し、更新されたレスポンスを提供します。
べき等リクエストを作成する
Using the SDK, provide an idempotency key with the idempotencyKey
property in API requests.
制限事項
- Test mode doesn’t support
/v2
; however, you can use a sandbox to test within this namespace. - The Go SDK doesn’t support
/v2
. - Stripe does not generate thin events for existing
/v1
endpoints and resources. - The CLI supports trigger and listen for
/v2
thin events; however, it doesn’t support/v2
resource creation. - The Developers Dashboard and Workbench don’t display
/v2
thin events on the global Events tab; however, we display/v2
thin events for each event destination in the Event deliveries tab.