apply-policy-to-api-instance

API インスタンスにポリシーを適用する

概要

組織と環境を選択し、対象 API を選び、利用可能なポリシーテンプレートのカタログを参照して、JSON スキーマを使用してポリシーを設定し、最後に API に適用することで、API Manager インスタンスにポリシーを適用します。このワークフローにより、API インスタンスと互換性のあるテンプレートのみを選択し、適用前に設定がテンプレートのスキーマに適合していることを確認できます。

作成するもの： 選択した API インスタンスに適用された、完全に設定済みのポリシー

前提条件

このワークフローを開始する前に、次のことを確認してください。

1. 認証の準備

   • Anypoint Platform 用の有効な Bearer トークン
   • API Manager の権限：View APIs Configuration および Manage Policies スコープ

2. 組織へのアクセス

   • 対象の API インスタンスが API Manager にデプロイ済みであること

ステップ 1：現在の組織を取得する

呼び出し元のプロフィールを取得し、ルート組織を自動的に特定します。パラメーターは不要です。Bearer トークンによってユーザーが識別され、子 Business Group（サブ組織）を含む組織の詳細が返されます。

必要なもの：

• 有効な Bearer トークン（認証ヘッダー）

操作： /me エンドポイントを呼び出して、現在のユーザーの組織を取得します。

api: urn:api:access-management
operationId: listMe
inputs: {}
outputs:
  - name: organizationId
    path: $.user.organization.id
    description: Root organization Business Group GUID
  - name: organizationName
    path: $.user.organization.name
    description: Organization display name

次の処理： 認証情報から導出されたルート組織 ID を取得できます。アカウントにサブ組織（子 Business Group）がある場合は、この ID を使って getOrganizations を呼び出し、一覧から適切なスコープを選んでから続行してください。

ステップ 2：環境を一覧表示する

組織内のすべての環境を一覧表示し、対象 API インスタンスが存在する環境（例：Production、Sandbox）を選択できるようにします。

必要なもの：

• ステップ 1 の組織 ID

操作： 利用可能な環境を一覧表示し、対象を選択します。

api: urn:api:access-management
operationId: listEnvironments
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
outputs:
  - name: environmentId
    path: $.data[*].id
    labels: $.data[*].name
    description: Selected environment ID

次の処理： 保護する API インスタンスが存在する環境を選択します。以降のすべてのステップで API Manager が環境 ID を必要とします。

ステップ 3：API インスタンスを一覧表示する

選択した環境内のすべての API インスタンスを取得します。各エントリは API Manager に登録された管理対象 API を表します。これがポリシーを適用する対象です。

必要なもの：

• ステップ 1 の組織 ID
• ステップ 2 の環境 ID

操作： API インスタンスを一覧表示し、ユーザーに 1 つ選んでもらいます。

api: urn:api:api-manager
operationId: listApiInstances
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
outputs:
  - name: environmentApiId
    path: $.assets[*].apis[*].id
    labels: $.assets[*].apis[*].instanceLabel
    description: The API instance ID to apply the policy to

次の処理： API インスタンスをユーザーに提示します。各アセットには複数のインスタンス（例：異なるバージョンやラベル）が含まれる場合があります。ユーザーが対象とする特定の environmentApiId を選択します。

ヒント：

• 一覧が大きい場合は、query パラメーターを使って名前で絞り込みます
• filters=active パラメーターを指定すると、アクティブなインスタンスのみが対象になります

ステップ 4：Exchange ポリシーカタログを参照する

組織で利用可能なすべてのポリシーテンプレートを Exchange から一覧表示します。このエンドポイントは、Exchange の完全な座標（groupId、assetId、version）と、各テンプレートのゲートウェイ互換の設定を返します。ポリシーを適用する際に、これらが必要です。

重要： 汎用の listPolicyTemplates エンドポイントではなく、api-portal-xapi エンドポイント（getExchangePolicyTemplates）を使用してください。汎用エンドポイントでは、ポリシー適用の手順で必要となる Exchange の座標や、ゲートウェイ固有の設定プロパティ名が返されません。

必要な情報：

• ステップ 1 の組織 ID
• ステップ 2 の環境 ID
• ステップ 3 の API インスタンス ID（互換性のあるテンプレートに絞り込むため）

操作： Exchange のポリシーテンプレートを一覧表示し、適用するテンプレートを選択します。apiInstanceId と environmentId を渡すと、API のゲートウェイタイプ（Omni Gateway、Mule Gateway など）に対応するテンプレートに絞り込めます。

api: urn:api:api-portal-xapi
operationId: getExchangePolicyTemplates
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
  apiInstanceId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 3 (filters for compatible templates)
  includeConfiguration:
    value: "true"
    description: Include the configuration schema for each template
  latest:
    value: "true"
    description: Return only the latest version of each template
outputs:
  - name: policyGroupId
    path: $[*].groupId
    labels: $[*].assetId
    description: Exchange group ID of the selected policy template
  - name: policyAssetId
    path: $[*].assetId
    description: Exchange asset ID of the selected policy template
  - name: policyAssetVersion
    path: $[*].version
    description: Exchange version of the selected policy template (gateway-compatible)
  - name: policyConfiguration
    path: $[*].configuration
    description: Configuration schema with gateway-compatible property names and defaults

次のステップ： ポリシーテンプレートの Exchange 座標と、ゲートウェイタイプに適したプロパティ名を含む設定スキーマが取得できました。ポリシーを適用する前に、policyConfiguration の出力を確認して、ポリシーで設定できる項目を把握してください。各設定プロパティについて、プロパティ名、説明、デフォルト値をユーザーに提示し、デフォルトのままにするか、カスタム値を指定するかを尋ねます。デフォルト値がないプロパティについては、必ずユーザーに値を尋ねてください。

よくある問題：

• リストが空の場合：ゲートウェイタイプに対応するテンプレートを取得するには、apiInstanceId と environmentId を渡してください。これらのフィルターがないと、一部のテンプレートが表示されないことがあります。
• 設定プロパティ名が誤っている場合：必ずこのエンドポイントから取得した設定を使用してください。汎用の listPolicyTemplates エンドポイントでは、異なる（ゲートウェイ互換ではない）プロパティ名やデフォルト値が返されることがあります。たとえば、Omni Gateway では credentialsOriginHasHttpBasicAuthenticationHeader が使用されますが、汎用テンプレートでは credentialsOrigin が使用されます。

ステップ 5：API インスタンスにポリシーを適用する

適切な設定を指定して、選択したポリシーを API インスタンスに適用します。ステップ 4 で取得した Exchange の座標と設定プロパティ名を使用してください。

必要な情報：

• これまでのステップで取得した組織 ID、環境 ID、API インスタンス ID
• ステップ 4 で取得したポリシーの Exchange 座標（groupId、assetId、assetVersion）
• ステップ 4 の policyConfiguration の出力に含まれるスキーマに基づいたポリシー設定

操作： API インスタンスにポリシーを適用します。ステップ 4 の設定スキーマに含まれるプロパティ名を使って、configurationData オブジェクトを作成してください。各設定プロパティについて、プロパティ名、説明、デフォルト値をユーザーに提示し、デフォルトのままにするか、カスタム値を指定するかを尋ねます。デフォルト値がないプロパティについては、必ずユーザーに値を尋ねてください。

api: urn:api:api-manager
operationId: applyApiInstancePolicy
inputs:
  organizationId:
    from:
      variable: organizationId
    description: Organization ID from Step 1
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
  environmentApiId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 3
  groupId:
    from:
      variable: policyGroupId
    description: Policy Exchange group ID from Step 4
  assetId:
    from:
      variable: policyAssetId
    description: Policy Exchange asset ID from Step 4
  assetVersion:
    from:
      variable: policyAssetVersion
    description: Policy Exchange version from Step 4
outputs:
  - name: policyId
    path: $.id
    description: The ID of the applied policy instance

次のステップ： API に選択したポリシーが適用され、保護された状態になりました。受信リクエストはポリシーのルールに基づいて評価されます。API に適用済みのポリシーを一覧表示するか、リクエストをテストして確認できます。

よくある問題：

• 400 Bad Request — groupId／assetId／assetVersion が不足している場合：適用エンドポイントには、テンプレート ID だけでなく、Exchange の完全な座標が必要です。これらの値を取得するために、getExchangePolicyTemplates（ステップ 4）を使用したことを確認してください。
• 400 Bad Request — configurationData が無効な場合：設定プロパティ名はゲートウェイタイプによって異なります。汎用のテンプレートエンドポイントから取得した名前ではなく、ステップ 4 の policyConfiguration の出力に含まれるプロパティ名を使用してください。たとえば、Omni Gateway では credentialsOriginHasHttpBasicAuthenticationHeader が使用されますが、汎用テンプレートでは credentialsOrigin が使用されます。
• 403 Forbidden：この環境で Manage Policies 権限が不足しています。
• 409 Conflict：このタイプのポリシーが API インスタンスにすでに適用されている可能性があります。既存のポリシーを一覧表示して確認するか、リクエスト URL に ?allowDuplicated=true を追加して、同じタイプのポリシーを 2 つ目のインスタンスとして適用してください。

完了チェックリスト

すべての手順が完了したら、ポリシーが正しく適用されていることを確認してください。

• 組織と環境を選択済み
• 対象の API インスタンスを特定済み
• 互換性のあるカタログからポリシーテンプレートを選択済み
• テンプレートの JSON スキーマに基づいて設定を作成済み
• ポリシーを正常に適用済み（ポリシー ID を含む 201 レスポンス）
• API のポリシー一覧にポリシーが表示されることを確認済み

作成したもの

✅ ポリシーの適用 — 選択したポリシーテンプレートが API インスタンスで有効になり、指定したパラメーターで設定されています。受信トラフィックはこのポリシーに照らして評価されます。

次のステップ

1. ポリシーを確認する — listApiPolicies で適用済みポリシーを一覧表示し、有効で正しく設定されていることを確認します。

2. 適用結果をテストする — API にリクエストを送信し、ポリシーが想定どおりに動作することを確認します（例：未認証のリクエストが拒否される、レート制限が適用される）。

3. 設定を調整する — updateApiPolicy を使用して、ポリシーを削除せずに設定を更新します。

4. ポリシーを追加で適用する — このワークフローを繰り返して、複数のポリシーを重ねて適用します（例：OAuth2 にレート制限を追加します）。reorderApiPolicies を使用して、実行順序を制御します。

5. 自動化ポリシーを検討する — このポリシーを組織内のすべての API に自動的に適用する場合は、createAutomatedPolicy を確認してください。

トラブルシューティング

適用後もポリシーが適用されない

症状： リクエストがポリシーによる評価を受けずに通過します

考えられる原因：

• API インスタンスがデプロイされていないか、エラー状態になっている
• ゲートウェイに新しい設定がまだ反映されていない（1～2 分お待ちください）
• ポリシー設定のデフォルト値が許可的で、すべてのトラフィックが許可されている
• pointcutData でテスト対象のエンドポイントが除外されている

解決方法：

• API Manager で API インスタンスのステータスを確認する
• 反映を待ってから再試行する
• ポリシー設定に過度に許可的な設定がないか確認する
• pointcutData を確認する — すべてのエンドポイントに適用するには省略します

ポリシー適用時の 400 エラー

症状： "The policy to be created is missing at least one of the following properties related to the policy template: 'groupId', 'assetId', 'assetVersion'."

考えられる原因：

• Exchange の座標を返さない汎用の listPolicyTemplates エンドポイントを使用した

解決方法：

• 代わりに api-portal-xapi の getExchangePolicyTemplates を使用します — 適用エンドポイントで必要な Exchange の座標一式が返されます

設定プロパティ名の不一致

症状： 無効な configurationData による 400 エラー

考えられる原因：

• ゲートウェイ互換のプロパティ名ではなく、汎用テンプレートエンドポイントのプロパティ名を使用した
• configurationData に必須フィールドがない
• データ型が正しくない（例：整数ではなく文字列）

解決方法：

• 必ず getExchangePolicyTemplates の configuration 出力を使用します（ステップ 4）— ゲートウェイ固有のプロパティ名が返されます
• たとえば、Omni Gateway では credentialsOriginHasHttpBasicAuthenticationHeader が使用されますが、汎用テンプレートでは credentialsOrigin が使用されます
• フィールドの型（数値、ブール値、配列）を正確に一致させます
• スキーマで定義されたフィールドのみを含めます

ポリシーテンプレートが見つからない

症状： ステップ 4 の結果が空です

考えられる原因：

• API インスタンスのゲートウェイタイプがそのテンプレートに対応していない
• apiInstanceId または environmentId のフィルターが指定されていない
• カスタムポリシーテンプレートがこの組織に公開されていない

解決方法：

• apiInstanceId と environmentId の両方を渡し、互換性のあるテンプレートに絞り込みます
• フィルターを削除してすべてのテンプレートを表示し、互換性を手動で確認します
• カスタムポリシーの場合は、listCustomPolicyTemplates でテンプレートが公開されていることを確認します

関連するスキル

• skill apply-universal-policy — あらゆるゲートウェイ上のインスタンスに、1つの Universal（正規）ポリシーを適用してポートフォリオの一部を保護します。ユーザーが「すべて」「多数」「自分の API」「特定のプロバイダー」と言った場合に使用します。
• skill apply-native-policy-to-instance — 適用済みのポリシーを一覧表示する、適用済みのネイティブポリシーを編集する、または MuleSoft Platform MCP Server（Kong／Apigee／Azure／MuleSoft）を通じてネイティブプラグイン／テンプレートを1つ適用します。「Apigee APIにはどのような保護が適用されていますか」や「IPフィルタリングを改善してください」の場合に使用します。
• deploy-api-with-rate-limiting — API の作成と OAuth2 を使用した段階的なレート制限を含む、完全なワークフローです。
• list-organization-api-instances — 環境全体にわたって既存の API インスタンスを検出します。
• manage-consumer-contracts — ポリシー適用後のクライアントアプリケーションのアクセスを管理します。