# 拡張の仕組み 拡張ポイントを使用して Stripe をカスタマイズする方法をご紹介します。 拡張機能を使用すると、[拡張ポイント](https://docs.stripe.com/extensions/extension-points.md)と呼ばれる Stripe の指定された場所でカスタムロジックを実行できます。Stripe がこれらの拡張ポイントでロジックを実行する必要がある場合、拡張機能が拡張ポイントに接続されているかどうかを確認し、接続されている場合はその拡張機能内のカスタムロジックを実行します。 たとえば、Stripe は[比例配分](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md)の拡張ポイントを定義します。この拡張ポイント用に構築された拡張機能を使用します。Stripe が比例配分の計算ステップに到達すると、デフォルトの比例配分ロジックではなく、その拡張機能のロジックが実行されます。拡張機能のロジックは比例配分する方法を決定し、比例配分金額を返します。Stripe は結果を使用して Billing フローを続行します。同様に、Stripe は[Workflows](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md)でカスタムアクション拡張ポイントを定義します。この拡張ポイント用の拡張機能は、メールの送信、CRM の更新、または定義したその他の操作を実行するためのコードを呼び出します。 ## モデルの仕組み Stripe は、コードを実行できる拡張ポイント (Stripe 製品内の指定された場所) を定義します。各拡張ポイントは以下を指定します。 - **入力**: 拡張ポイントに達したときに Stripe が拡張に送信するデータ。拡張ユーザーからの入力も含まれます。 - **出力**: 拡張が Stripe に返す必要があるデータ - **許可されている実装タイプ**: その拡張ポイントで使用できる実装タイプ (スクリプト、リモート関数、またはその両方) (See full diagram at https://docs.stripe.com/extensions/how-extensions-work) まず、ユースケースの[拡張ポイント](https://docs.stripe.com/extensions/extension-points.md)を見つけます。 カスタムロジックは、拡張ポイントに接続する拡張機能として構築します。拡張機能は、インストール、権限、配布を処理する [Stripe Apps](https://docs.stripe.com/stripe-apps.md) の一部としてパッケージ化されます。同じアプリ内に、[スクリプト](https://docs.stripe.com/extensions/how-extensions-work.md#scripts)、[リモート関数](https://docs.stripe.com/extensions/how-extensions-work.md#remote-functions)、[UI 拡張機能](https://docs.stripe.com/extensions/how-extensions-work.md#ui-extensions)など、任意の実装タイプの複数の拡張機能をパッケージ化できます。アプリには[カスタムオブジェクト](https://docs.stripe.com/custom-objects.md)を含めることもできます。 ## 実装タイプ 各拡張ポイントは、1 つ以上の実装タイプに対応しています。実装タイプによって、コードが実行される場所と外部サービスとのやり取り方法が決まります。 ### スクリプト スクリプトは、Stripe のフルマネージドランタイムで実行される TypeScript のメソッドです。Stripe がコードを実行し、Stripe CLI を通じてアプリをアップロードしてデプロイするため、インフラストラクチャをホストする必要はありません。 スクリプトは、Stripe が拡張ポイントに到達するとビジネスロジックを実行します。スクリプトは、次の場合に使用します。 - 顧客の購入履歴や販売イベントに基づいて割引を計算するなど、コードを使用して複雑なビジネスルールを適用します。 - 顧客が利用資格を満たしているかどうかを確認するなど、Stripe が処理する前にデータを検証または変換します。 - Webhook を構築および維持することなく、外部データを Stripe のオペレーションに統合します。 - 独自のサービスをデプロイおよび管理することなく、迅速にプロトタイプを作成できます。 スクリプトで実行できることは、拡張ポイントによって異なります。 - **Billing 拡張ポイント** (顧客残高、項目処理、比例配分)では、スクリプトは Stripe からデータを受け取り、ロジックを実行して結果を返します。外部 API コールは許可されていません。これらの拡張ポイントは Billing パイプラインで実行され、Stripe は信頼性を維持するために副作用を制限します。 - \**カスタムアクション拡張ポイント **(Workflows 向け): スクリプトは `endpointFetch()` を使用して外部 HTTP 呼び出しを実行できます。エンドポイントはアプリのマニフェストで宣言し、Stripe は[Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md)を通じてシークレットの保存と認証情報の挿入を処理します。これは、インフラストラクチャを管理しなくても外部サービスにアクセスするアクション向けに設計されています。 **制限事項:** サードパーティへの依存はありません。`endpointFetch()` を使用した Workflows カスタムアクションの外部 API コールのみ可能です。TypeScript のみをサポートします。制約の一覧については、[スクリプト実行時動作](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md#script-runtime-behavior)をご覧ください。 ### リモート関数 リモート関数は、お客様独自のインフラストラクチャでホストする HTTP エンドポイントです。拡張ポイントに到達すると、Stripe はエンドポイントを呼び出し、各リクエストに [Webhook 署名](https://docs.stripe.com/webhooks.md#verify-official-libraries)で署名するため、そのリクエストが Stripe から送信されたことを検証できます。 コードが呼び出すすべての外部サービスの認証はお客様が管理します。Stripe はリモート関数にシークレットを注入しません。受信した Stripe の署名を検証し、送信時の認証もご自身で処理します。 次のような場合にリモート関数を使用します。 - 自社サーバーまたは自社環境でロジックを実行できます - ERP や CRM などの自社システムと連携できます - TypeScript 以外の言語を使用できます **制限事項:** ホスティング、可用性、デプロイはお客様が管理します。エンドポイントは、拡張ポイントで定義されたタイムアウト以内に応答する必要があります (たとえば、カスタムアクションでは 20 秒)。 ### UI 拡張 Stripe ダッシュボード内に表示される React コンポーネント。UI 拡張を使用すると、ダッシュボードユーザーにカスタム UI を表示できます。[UI 拡張](https://docs.stripe.com/stripe-apps/how-ui-extensions-work.md)を確認してください。 ### 実装タイプの選択 拡張ポイントがスクリプトとリモート関数の両方に対応している場合は、次の表を使用して判断してください。 | 検討事項 | スクリプト | リモート関数 | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | 実行場所 | Stripe のマネージドランタイム | お客様のインフラストラクチャ | | 言語 | TypeScript | 任意の言語 (HTTP エンドポイント) | | 外部 API コール | 拡張ポイントによって異なります。カスタムアクションでは `endpointFetch()` を通じて使用できます。請求拡張ポイントでは使用できません。 | はい。サーバーから直接呼び出しを行います | | 外部サービスの認証 | Stripe は、エンドポイント設定と [Secret Store](https://docs.stripe.com/stripe-apps/store-secrets.md) を通じてシークレットを注入します (外部 API コールが許可されている場合)。 | お客様自身で認証を管理します | | Stripe からお客様のコードへの認証 | 該当なし。コードは Stripe 上で実行されます | Stripe は各リクエストに署名します。[Webhook 署名を検証します](https://docs.stripe.com/webhooks.md#verify-official-libraries)。 | | 最適な用途 | 独自のインフラを必要としないロジック | 独自のシステム、変換処理、または TypeScript 以外の言語を必要とするロジック | | 制限事項 | サードパーティーへの依存関係なし、直接の `fetch()` は使用不可、TypeScript のみ | ホスティング、可用性、デプロイを自社で管理します | ## 権限 拡張機能を構築する際には、拡張機能に必要な権限を宣言する必要があります。拡張機能は、読み取りまたは書き込みの権限が付与されたデータにのみアクセスできます。拡張機能のユーザーは、拡張機能を含むアプリをインストールする際にこれらの権限を付与します。すべての[権限](https://docs.stripe.com/stripe-apps/reference/permissions.md)の一覧をご覧ください。 ## ライフサイクル 拡張機能の作成は、次のライフサイクルに従います。 1. **構築**: Stripe アプリ内に拡張機能を構築します。 1. **アップロード**: Stripe CLI を使用してアプリをアップロードします。Stripe がアプリを処理し、インストールできるようにします。 1. **バージョン** (オプション): 改良を重ねながら新しいバージョンをアップロードします。 1. **公開** (オプション): [外部テストチャネル](https://docs.stripe.com/stripe-apps/test-app.md)または [Stripe App Marketplace](https://docs.stripe.com/stripe-apps/publish-app.md) を介してアプリを共有します。アプリは、各自のアカウントにインストールできるようになります。 1. **インストール**: ユーザーまたはアプリの共有先がインストールし、関連する権限を受け入れます。 1. **有効化**: アプリのユーザーが拡張ポイントで拡張機能を有効化します。 1. **呼び出し**: Stripe は、拡張ポイントに到達するたびに、有効化された拡張機能を呼び出します。 1. **無効化**: アプリのユーザーが拡張機能を無効化します。アカウントには残りますが、拡張ポイントに到達すると Stripe から呼び出されなくなります。 1. **アンインストール**: アプリのユーザーがアカウントからアプリとその拡張機能を削除します。 ## 構築を開始 どのガイドに従うかは、構築する拡張ポイントによって異なります。 - 顧客残高、項目処理、または比例配分の動作をカスタマイズするには、[Billing スクリプト拡張機能を作成](https://docs.stripe.com/extensions/scripts/build-prorations-extension.md)します。 - [スクリプトを使用してカスタムワークフローアクションを作成](https://docs.stripe.com/extensions/custom-actions/build-with-script.md)するか、[リモート関数](https://docs.stripe.com/extensions/custom-actions/build-with-remote-function.md)を使用します。[カスタムアクションの仕組み](https://docs.stripe.com/extensions/custom-actions/how-custom-actions-work.md)の詳細をご確認ください。 利用可能な拡張ポイントとサポートされる実装タイプの完全な一覧については、[拡張ポイント](https://docs.stripe.com/extensions/extension-points.md)をご覧ください。