使用計画の作成

API Gatewayを使用してバックエンド・サービスに送信されたリクエストの数を監視および管理するための戦略の一環として、使用プランを作成する方法をご紹介します。

APIプラン・マネージャとして、使用プランおよびサブスクライバを作成して、APIアクセスを監視および管理し、アクセス層を設定できます。「使用プランおよび権限、サブスクライバおよびクライアント・トークン」を参照してください。

使用プランには、1つ以上のターゲットAPIデプロイメントを含む権限を含めることができ、オプションで、その権限のレート制限と割当て制限を指定できます。特定の期間内のリクエスト数が権限のリクエスト割当てを超えた場合は、リクエストを許可し続けるか拒否するかを指定できます。割当て制限を超えているためにリクエストが拒否された場合は、リクエストが再試行されるタイミングがレスポンス・ヘッダーに示されます。

複数の権限で構成される使用プランを作成して、APIデプロイメントごとに異なるレート制限および割当てを指定できます。

使用プランを作成するには、使用プランを作成するAPIデプロイメントがすでに存在している必要があります。また、APIデプロイメントは、使用計画に含める資格をすでに取得している必要があります(使用計画に含めるためのAPIデプロイメントの適格化を参照)。

次に注意してください:

使用プランに複数のAPIデプロイメントに対する権限が含まれている場合、指定したレート制限または割当て制限は、権限内のAPIデプロイメント間で共有されます。
使用プランには、同じAPIデプロイメントのレート制限または割当て制限を指定する異なる権限を含めることはできません。つまり、APIデプロイメントは、異なる使用プランの複数の資格のターゲットとして指定できますが、同じ使用プランの複数の資格に指定することはできません。
異なるAPIゲートウェイのAPIデプロイメントを同じ権限に含めることができます。
資格にレート制限または割当て制限(あるいはその両方)を指定しない場合、無制限のレート制限または割当て制限(あるいはその両方)が、資格のターゲットAPIデプロイメントに適用されます。権限にレート制限または割当て制限(あるいはその両方)が指定されていない場合でも、ターゲットAPIデプロイメントにアクセスするには、APIクライアントは引き続き使用プランにサブスクライブする必要があり、クライアント・トークンを渡す必要があることに注意してください。
使用プランを更新し、資格/権利の目標期間を別の期間(たとえば、曜日から週)に変更すると、新しい要求番号カウントが開始されます。ただし、その後使用プランを再度更新し、目標期間を元の値に戻すと、以前のリクエスト番号カウントが再開されます(その間に新しい期間が開始されていない場合、カウントはゼロにリセットされます)。
APIデプロイメントを使用プランに含めると、サブスクライブされたAPIクライアントからAPIデプロイメントへのリクエストには、使用プランのリクエスト・ポリシーで指定された場所にクライアント・トークンを含める必要があります。HTTP-403エラーは、指定された場所にクライアント・トークンを含まないリクエスト、およびサブスクライブ解除されたAPIクライアントからのリクエストに応答して返されます。
HTTP-4xxエラー・レスポンスを返すリクエストは、権限の割当て制限とそのレート制限の両方にカウントされます。HTTP-5xxエラー・レスポンスを返すリクエストは、資格のレート制限にカウントされますが、割当て制限にはカウントされません。
使用プランの資格にターゲットとして含まれるAPIデプロイメントへのリクエストを受信すると、APIゲートウェイは、資格レート制限および割当てをチェックする前に、認証および認可チェックを実行します。認証および認可チェックに失敗したリクエストは、資格の割当て制限またはそのレート制限のいずれにもカウントされません。
最初に権限がない使用プラン定義を作成し、後で追加できます。使用プラン定義に資格を追加するまで、使用プランを使用してAPIにアクセスすることはできません。

次の方法で、使用プランを作成できます。

コンソールの使用
CLIおよびJSONファイルの使用

コンソールを使用した使用プランの作成

コンソールを使用して新しい使用プランおよび1つ以上の資格を作成するには:

「使用プラン」リスト・ページで、「使用プランの作成」を選択します。リスト・ページの検索に関するヘルプが必要な場合は、使用計画のリストを参照してください。
使用プランに次の値を指定します:
- 名前:新しい使用計画の名前。たとえば、Gold-usage-planです。機密情報の入力は避けてください。
- コンパートメント:新規使用プランが属するコンパートメント。
オプションで、「拡張オプション」を選択し、次を指定します:
- タグ: リソースの作成権限がある場合は、そのリソースにフリーフォーム・タグを適用する権限もあります。定義済タグを適用するには、タグ・ネームスペースを使用する許可が必要です。タグ付けの詳細は、リソース・タグを参照してください。タグを適用するかどうかがわからない場合は、このオプションをスキップするか、管理者に問い合せてください。後でタグを適用できます。
「次」を選択して、使用プランにサブスクライブしたAPIコンシューマおよびAPIクライアントにアクセス権があるAPIデプロイメントを指定します。

使用プランは権限で構成されます。各権限は、使用プランのサブスクライバがリクエストを送信する権限がある1つ以上のターゲットAPIデプロイメントと、送信する権限があるリクエストの数を指定します。
「権限」ページで、次の手順を実行します。
1. 「権限の作成」を選択し、使用プランの最初の権限の詳細を指定します:
  - 名前: 新しい権限の名前。権限名は、使用プラン内で一意である必要があります。たとえば、Entitlement1です。機密情報の入力は避けてください。
  - 説明:新しい資格の説明。たとえば、Basic entitlement for all usage plansです。機密情報の入力は避けてください。
  - レート制限: (オプション)「レート制限の有効化」を選択して、1秒当たりに許可するリクエストの最大数を「リクエスト/秒」として指定します。
  - 割当て制限: (オプション)「割当て制限の有効化」を選択して、特定の期間に許可するリクエストの最大数を指定します:
    - リクエスト:許可するリクエストの最大数。
    - 期間: 最大リクエスト数が適用される期間。「分」、「時間」、「日」、「週」または「月」のいずれか。
    - ポリシーのリセット:リクエスト数をゼロにリセットする場合。Calendarリセットポリシーがサポートされています。「カレンダ」リセット・ポリシーでは、「期間」で指定された新しい期間の開始時に、リクエスト番号カウントがゼロにリセットされます。
      
      たとえば、[期間]が [日]に設定されている場合、休暇付与が最初に作成されるとき、リクエスト番号カウントは最初はゼロに設定されます。カウントは、翌日の開始時(UTC午前0時)にゼロにリセットされます。カウントは、翌日の開始時にゼロにリセットされます。
    - 違反に対する操作:指定した期間内の最大リクエスト数を超えた場合の処理。「拒否」を指定すると、期間内の追加リクエストは拒否され、HTTP-429 Too Many Requestsレスポンスが返されます。レスポンスには、新しいリクエストを行うまでに待機する時間を示すRetry-Afterヘッダーが含まれます。「許可」を指定すると、期間内の追加リクエストは引き続き許可されます。
  - ターゲット・デプロイメント: 「デプロイメントの追加」を選択して、権限に含める最初のAPIデプロイメントを指定します:
    - ゲートウェイ: APIデプロイメントが作成されたAPIゲートウェイを選択します。APIゲートウェイは、使用プランと同じコンパートメントに属することができますが、その必要はありません。
    - デプロイメント:権限に含めるAPIデプロイメントを選択します。APIデプロイメントは、使用プランと同じコンパートメントに属することができますが、その必要はありません。
      クライアント・トークンの場所を指定して、使用計画に含めるためのAPIデプロイメントをすでに適格にしている必要があることに注意してください(使用計画に含めるためのAPIデプロイメントの適格化を参照)。
    「保存」を選択して、権限に含まれる最初のAPIデプロイメントの詳細を保存します。オプションで、「デプロイメントの追加」を再度選択して、使用プランの最初の資格に含める追加のAPIデプロイメントを指定します。
2. 「保存」を選択して、使用プランの最初の資格を保存します。
3. オプションで、「権限の作成」を再度選択し、使用プランに含める追加の権限の詳細を指定します。
「次」を選択して、使用プラン用に入力した詳細を確認します。
「作成」を選択して使用プランを作成します。
新しい使用計画の作成には数分かかる場合があります。作成中、使用プランは「使用プラン」ページに「作成中」の状態で表示されます。正常に作成されると、新規使用プランが「アクティブ」の状態で表示されます。
また、新しい使用プランをすぐに作成するのではなく、リソース・マネージャおよびTerraformを使用して後で作成するには、「スタックとして保存」を選択してリソース定義をTerraform構成として保存します。リソース定義からのスタックの保存の詳細は、「リソース作成ページからのスタックの作成」を参照してください。
使用プランがアクティブ状態で表示されるまで数分以上待機した場合(または使用プランの作成操作が失敗した場合):
1. 使用プランの名前を選択し、「作業リクエスト」を選択して使用プラン作成操作の概要を表示します。
2. 「使用計画の作成」操作を選択すると、操作に関する詳細情報(エラー・メッセージ、ログ・メッセージ、関連付けられたリソースのステータスなど)が表示されます。
3. 使用計画の作成操作が失敗したため、作業要求情報から問題の原因を診断できない場合は、APIゲートウェイのトラブルシューティングを参照してください。

CLIおよびJSONファイルを使用した使用プランの作成

CLIを使用して新しい使用プランおよび1つ以上の資格を作成するには:

任意のJSONエディタを使用して、次の形式の使用プラン定義ファイルを作成します。
```
{
    "displayName": "<usage-plan-name>",
    "entitlements": [{
        "name": "<entitlement-name>",
        "description": "<entitlement-description>",
        "rateLimit": {
            "value": <rate-limit-value>,
            "unit": "<rate-limit-unit>"
        },
        "quota": {
            "value": <quota-value>,
            "unit": "<quota-unit>",
            "resetPolicy": "CALENDAR",
            "operationOnBreach": "<REJECT|ALLOW>"
        },
        "targets": [{
            "deploymentId": "<target-deployment-ocid>"
        }]
    }],
    "compartmentId": "<compartment-ocid>",
    "freeformTags": {},
    "definedTags": {}
}
```
ここでは:
- "displayName": "<usage-plan-name>"は、新しい使用計画の名前です。たとえば、"displayName": "Gold-usage-plan"です。機密情報の入力は避けてください。
- "entitlements": [{...}]は、1つ以上の権限の詳細を指定します。ここでは:
  - "name": "<entitlement-name>"は、新しい権限の名前です。権限名は、使用プラン内で一意である必要があります。たとえば、"Entitlement1"です。機密情報の入力は避けてください。
  - "description": "<entitlement-description>"は、新しい権限の説明です。たとえば、"description": "Basic entitlement for all usage plans"です。機密情報を入力しないでください..
  - "rateLimit": {...}はオプションで、1秒当たりに許可する最大リクエスト数を指定します。レート制限を定義する場合は、次のすべての値を含める必要があります。
    - "value": <rate-limit-value>は、許可するリクエストの最大数です。たとえば、"value": 100です。
    - "unit": "<rate-limit-unit>"は、レート制限の時間の単位です。 "SECOND"に設定する必要があります。
  - "quota": {...}は、オプションで、特定の期間に許可する最大リクエスト数を指定します。目標を定義する場合は、次のすべての値を含める必要があります。
    - "value": <quota-value>は、期間ごとに許可するリクエストの最大数です。たとえば、"value": 1000です
    - "unit": "<quota-unit>"は、リクエストの最大数を適用する期間です。MINUTE、HOUR、DAY、WEEKまたはMONTHのいずれかに設定する必要があります。("unit": "MONTH"など)。
    - "resetPolicy": "CALENDAR"は、リクエスト数のカウントがゼロにリセットされる場合です。CALENDARリセット・ポリシーがサポートされています。CALENDARリセット・ポリシーでは、"unit"で指定されたように、新しい各期間の開始時にリクエスト番号数がゼロにリセットされます。
      たとえば、"unit": "DAY"の場合、権限が最初に作成されるとき、リクエスト番号数は最初はゼロに設定されます。カウントは、翌日の開始時(UTC深夜)にゼロにリセットされます。カウントは、翌日の開始時にゼロにリセットされます。
    - "operationOnBreach": "<REJECT|ALLOW>"は、割当て制限の期間内の最大リクエスト数を超えた場合の動作を指定します。REJECTを指定すると、期間内の追加リクエストは拒否され、HTTP-429 Too Many Requestsレスポンスが返されます。レスポンスには、新しいリクエストを行うまでに待機する時間を示すRetry-Afterヘッダーが含まれます。ALLOWを指定すると、期間内の追加リクエストが許可されます。たとえば、"operationOnBreach": "REJECT"です。
  - "targets": [{...}]は、使用プランのサブスクライバがアクセスできる1つ以上のターゲットAPIデプロイメントを指定します。ここでは:
    - "deploymentId": "<target-deployment-OCID>"は、資格に含めるAPIデプロイメントのOCIDです。APIデプロイメントは、使用プランと同じコンパートメントに属することができますが、する必要はありません。たとえば、"deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"です。
      クライアント・トークンの場所を指定して、使用計画に含めるためのAPIデプロイメントをすでに適格にしている必要があることに注意してください(使用計画に含めるためのAPIデプロイメントの適格化を参照)。
- "compartmentId": "<compartment-OCID>"は、新しい使用プランが属するコンパートメントのOCIDです。たとえば、"ocid1.compartment.oc1..aaaaaaaa7______ysq"です。
例:
```
{
    "displayName": "Gold-usage-plan",
    "entitlements": [{
        "name": "Entitlement1",
        "description": "Basic entitlement for all usage plans",
        "rateLimit": {
            "value": 100,
            "unit": "SECOND"
        },
        "quota": {
            "value": 1000,
            "unit": "MONTH",
            "resetPolicy": "CALENDAR",
            "operationOnBreach": "REJECT"
        },
        "targets": [{
            "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
        }]
    },
    {
        "name": "Entitlement2",
        "description": "Gold plan entitlement",
        "rateLimit": {
            "value": 200,
            "unit": "SECOND"
        },
        "quota": {
            "value": 5000,
            "unit": "WEEK",
            "resetPolicy": "CALENDAR",
            "operationOnBreach": "REJECT"
        },
        "targets": [{
            "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
          },
          {
            "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaac______nxd"
          }
        ]
      }
    ],
    "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq"
}
```
使用プラン定義ファイルを任意の名前で保存します。例: gold-usageplan.json
使用プラン定義ファイルを使用して、CLIを使用して使用プランを作成します:
1. CLIを使用するためにクライアント環境を構成します(APIゲートウェイ開発用のCLIを使用するためのクライアント環境の構成)。
2. コマンド・プロンプトを開き、oci api-gateway usage-plan createを実行して、使用プラン定義ファイルから使用プランを作成します。
```
oci api-gateway usage-plan create --from-json file://<usageplan-definition>.json
```
  ここでは:
  - --from-json file://<usageplan-definition>.jsonは、パスを含む使用プラン定義を含むファイルです。
  例:
```
oci api-gateway usage-plan create --from-json file://gold-usageplan.json
```
  コマンドへのレスポンスには、次が含まれます:
  - 使用プランのOCIDおよびその他の詳細。
  - ライフサイクルの状態(たとえば、ACTIVE、FAILED)。
  - 使用プランを作成する作業リクエストのID(作業リクエストの詳細は、完了、取消または失敗の後の7日間利用可能です)。
  使用プランがアクティブになる(またはリクエストが失敗する)までコマンドが制御を返すのを待機する場合は、次のいずれかまたは両方のパラメータを含めます:
  - --wait-for-state ACTIVE
  - --wait-for-state FAILED
  例:
```
oci api-gateway usage-plan create --from-json file://gold-usageplan.json --wait-for-state ACTIVE
```
  作業リクエストが正常に作成され、使用プランがアクティブになるまで、使用プランは使用できません。
3. (オプション)使用プランのステータスを表示するには、次のように入力します。
```
oci api-gateway usage-plan get --usage-plan-id <usage-plan-ocid>
```
4. (オプション)使用プランを作成している作業リクエストのステータスを確認するには、次を入力します:
```
oci api-gateway work-request get --work-request-id <work-request-ocid>
```
5. (オプション)使用プランを作成している作業リクエストのログを表示するには、次を入力します:
```
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
```
6. (オプション)使用プランを作成している作業リクエストが失敗し、エラー・ログを確認するには、次を入力します:
```
oci api-gateway work-request-error --work-request-id <work-request-ocid>
```
CLIの使用の詳細は、コマンドライン・インタフェース(CLI)を参照してください。CLIコマンドで使用できるフラグおよびオプションの完全なリストについては、CLIのヘルプを参照してください。

APIの使用

APIの使用およびリクエストの署名の詳細は、REST APIのドキュメントおよびセキュリティ資格証明を参照してください。SDKの詳細は、SDKおよびCLIを参照してください。

CreateUsagePlan操作を使用して、使用プランを作成します。

Oracle Cloud Infrastructureドキュメント

使用計画の作成

コンソールを使用した使用プランの作成

CLIおよびJSONファイルを使用した使用プランの作成

APIの使用