API Management overview v0.2.24.0726

Azure API Management の概要説明資料です。

併せて公式ドキュメントもご参照ください。
https://learn.microsoft.com/ja-jp/azure/api-management/

トレーニング用のコンテンツは下記からご参照いただけます。
https://learn.microsoft.com/ja-jp/training/browse/?expanded=azure&products=azure-api-management

Transcript

1. Ayumu Inaba Technical Specialist Microsoft Japan Azure API Management 1
2. Agenda API Management 概要 基本的な利用方法 API ライフサイクルを支える機能 セキュリティの考慮事項 利用料金と可用性 Appendix 参考情報 IaC による APIM の構成 2
3. API Management 概要 3
4. シナリオ Data and services APIs Connected experiences バックエンドアーキテクチャの多様性と 複雑性を抽象化 内外のユーザーが API を検出して 使用できるように API として Azure 内外でホストされる サービスを安全に公開 API の保護、高速化、監視を集中化
5. Frictionless consumption Self-service user onboarding Front door Single point of ingress Essence of API management Facade Hide backends from frontends Move backends without impacting frontends Re-architect backends without impact on frontends Expose a subset of backend capabilities Aggregate or slice backends into APIs Modernize legacy backends Decouple frontend developers with mocks Route Authenticate Authorize Throttle Transform Trace Meter Discover APIs Learn how to use APIs Try APIs without writing any code Request and receive access to APIs Download API specs, samples, and SDKs Interact with the API provider Get usage reports
6. API Management コンポーネント 6
7. API Management コンポーネント API Gateway (Data plane) バックエンドサービスのファサードとして機能、クライアントアプリの要求はゲートウェイに到着してからバックエン ドサービスに転送される ルーティング、セキュリティ、調整、キャッシュ、可観測性といった一般的な API で必要とされる横断的関心事に 対応 コンテナ化されたセルフホステッド ゲートウェイを利用することで、API をホストする環境にゲートウェイ機能を提 供、トラフィックを最適化することも可能 Management plane サービス設定や各種 API のスキーマ定義やインポート、製品のパッケージ化、ポリシーの設定、監視とインサイト、 ユーザー管理などを行う その他のサービスと同様に Azure Portal, CLI, REST API, VS Code, クライアント SDK といった管理ツー ルが利用可能 Developer Portal (User Plane) API を利用してカスタムアプリを開発する開発者が API の検出、使用方法の学習、キー管理などをセルフサー ビスで行うことで API の利活用を促進する 登録された API 定義をもとに自動生成された Web サイトとして提供、カスタマイズも可能 7
8. 基本的な使用方法 8
9. API ライフサイクル 構築 発行 利用 運用 ビジネス要求を満たすように API のインタフェースを設計 各種 サービスや言語を使用し て、実際の機能やデータを提供 する API を構築 既存の API を利用する、ある いは APIM 登録用のラッパー API の実装などを行う場合も ある API 開発者 API 利用者に提供されるインタ フェースや製品としての登録な どを行う バージョニング、セキュリティ設 定、負荷分散、ロギングなどの 付加価値を実装 API 利用時のキー発行などア クセス制御を行う API 管理者 API 管理者 アプリ開発者 開発者ポータルを使用して、 API 仕様の確認や動作確認を 行う サブスクリプション作成し、開発 するクライアントアプリに API を組み込む API の使用量や正常性などを 監視、API/アプリ開発者に フィードバックを行う 必要に応じてスケールアウトな どの運用対処を実施 バージョン アップ 機能追加、バグ修正、性能向上 などの各種アップグレードを行 う 新バージョンの登録、並行稼働 運用の開始 必要に応じて API バージョン アップに応じたクライアントアプ リのアップグレードを行う 新旧バージョンの利用状態の 把握や必要に応じて旧バージョ ンの停止などを行う
10. API の管理 Azure Portal で API の定義や設定を行う Open API の定義やインポート、各種ポリシーの設定、認証、ネットワーク、製品やサブスクリ プションの管理、開発者ポータルの発行、ユーザー管理、監視、分析、etc… ここで設定した内容が各 Gateway に配信されファサードとして動作することになる 11
11. API 発行 12 新規に API を定義することもできるが、、、 既に API を定義したファイルが存在する場 合はインポートするとよい API 実装が Azure 上でホストされている 場合には、直接インポートも可能
12. API 発行 - HTTP API の手動定義 １つの API に対して複数の Operation を登録して管理する API Management には複数の API を登録することが可能なため、クライアントから API および Operation をパスとメソッドで呼び分けることになる {METHOD} https://{apimName}.azure-api.net/{apiUrlSuffix}/{operationPath} さらに各 Operation に対して、パラメータ、リクエスト/レスポンスのデータ定義を行う（必須ではない） 13
13. API 発行 - OpenAPI 仕様のインポート OpenAPI 定義（旧 Swagger）が利用可能な場合はイン ポートするのが手っ取り早い 既に OpenAPI 仕様で実装された API への呼び出しを中継する場合、基本的に APIM で 管理すべき API 定義も同じものになるため 単純な中継でなくとも、API 定義の保守・運用に一般的なツールが利用可能になり、 ソース 管理できるメリットもあるため OpenAPI 仕様による管理は検討しておくとよい 14 API 仕様 API Provider API Consumer API Management
14. API 発行 - テスト実行 登録した各オペレーションのテスト画面から実際に呼び出し のテストを行うことができる Trace 機能を使用すると後述のポリシーの挙動など内部処理なども確認できるので、エラー 発生時などに活用するとよい 15
15. API 発行 - ポリシーによる付加価値の実装 様々なスコープのポリシー設定で API の動作をカスタマイズ CORS 設定、呼び出し回数によるスロットリング、呼び出し元のアクセス制御、バックエンド API の保護、URL Ｒ ｅｗｒｉｔｅ、キャッシュ、モック応答、etc… 16 global product api operation inbound outbound to backend from backend from caller to caller GET /foo/bar HTTP/1.1 Host: api.constoso.com Key: 0123456789 0123456789 /foo /bar CORS LOG RATE QUOTA JWT CACHE URL BODY
16. API 発行 - ポリシー設定のスコープ 共通のポリシーはより上位レベルで、個別の処理は下位レベ ルで設定する これ以外にも後述の製品レベルでポリシーを設定することも可能 17 全 API に適用 されるポリシー 個別 API の全 Operation のポリシー 特定 API の特定 Operation のポリシー base ポリシーで上位ポリシーを継承 （上書きも可能）
17. [補足] API Management の基本挙動 既定ではフロントエンドへのリクエストからバックエンドの転送は以下の ように行われる URL に含まれるドメインから API Management インスタンスが決まる パスとメソッドから API および Opearation が決まる 各スコープで設定されたポリシーがマージされて処理される 既定では All APIｓ 設定された forward-request ポリシーによって、各 ＡＰＩ の Web service URL に転送される 18 API Management API Operation Operation API POST https://apimName.azure-api.net /api-name /operation-name ※ API の設定でサブスクリプションが必要に 設定されている場合には API キーも 送信する必要がある Web service URL ｈｔｔｐｓ://backend.example.com POST https://backend.example.com /operation-name ※ ヘッダー、ボディ、クエリ文字列などは そのまま後ろに転送される
18. [補足] API Management の基本挙動 既定では全ての API スコープに対して、backend で forward- request ポリシーが設定されている 転送先の URL は API のインポートや作成時に指定した URL が利用される（ Settings 画面で確認） このため最低限 Operation とメソッドさえ登録されていればバックエンドへの転送が行われることになる この挙動のカスタマイズや機能追加を各スコープの「Policy」や「Settings」で行う 19
19. [補足] API Management の基本挙動 既定では各 API に対して「サブスクリプションが必要」になっ ており、API キーを利用しないとアクセスできない 匿名アクセスを許可したい、あるいは OAuth 等の異なる認可方式のみで制御したい場合は このチェックを外すと API キーは不要になる 20
20. API 発行 - ポリシーの実装 ポリシーは XML ドキュメントの形で定義される inbound/outbound/backend/on-error の4セクションで構成され、各セクションに記述 できるポリシーリファレンスで確認できる Azure Portal のGUI を使った簡易的な編集も可能だが、複雑なポリシーの場合は直接 XML を編集する必要がある 21
21. API 発行 - ポリシーの実装例 22 <!-- バックエンドを動的に切り替える --> <set-backend-service id="apim-generated-policy" base-url="https://your-resource-name.openai.azure.com/openai" /> <!-- バックエンド呼び出しに Managed ID を」使用する--> <authentication-managed-identity resource="https://cognitiveservices.azure.com/" /> <!-- API Header を設定する--> <set-header name="x-backend-apikey" exists-action="append"> <value>hogehoge</value> </set-header> <!-- エラー応答を返す--> <return-response> <set-status code="400" reason="Bad Request" /> <set-body>{ "error": { "code": "OperationNotSupported", "message": "Your request operation is not supported" } }</set-body> </return-response> <!-- ４２９ Too Many Request エラーが発生した場合は別のバックエンドに切り替えてリトライする --> <retry condition="@(context.Response.StatusCode == 429)" count="1" interval="0"> <choose> <when condition="@(context.Response.Body != null)"> <set-backend-service id="sub-instruct-backend-policy" backend-id="sub-backend" /> </when> </choose> <forward-request buffer-request-body="true" /> </retry> C# ベースの“式”を記述することも可能
22. API 発行と利用 1つ以上の API を製品として束ね、グループに対してアクセス許可 を割り当てる グループに属するユーザーはサブスクリプションを作成することでキーを取得できる ＡＰＩ に対して直接サブスクリプションを割り当てることも可能 23 Product Group User Subscription Built-in: Guest, Developer, Admin Custom: native or Azure AD 1 1 many many many many API many many 1 1 many 1 0..1 many
23. API 発行と利用 - 集中管理型 既定の設定では API およびそれを束ねる製品を利用するために はサブスクリプションと API キーの発行が必要 24 Data plane Management plane API Apps on devices App developers Abstract and decouple Secure and protect Revise and version Monitor and measure Publish and monetize API providers Gateway ② アプリ開発とキーの組み込み ① サ ブ ス クリプ シ ョン と API キ ー の 発 行 ③ API キ ー を 使 用 した 呼 び 出 し ④ バ ックエ ンド API が 呼 び 出 され る
24. API 発行と利用 - 集中管理型 「管理操作として」製品やAPIに対するサブスクリプションを 作成、 API キーを取得して開発者に対してキーを払い出す これは開発者の認証に基づいたセルフサービス型の操作ではなく、APIM 管理者側での操 作であることに注意 システム連携の API など個別に少数の API キーを払い出す運用シナリオに向いている 25
25. API 発行と利用 - セルフサービス型 開発者セルフサービスでの API キー発行のためには開発者 ポータルを利用する User plane Data plane Management plane API Apps on devices App developers Discover Learn Try Onboard Get help Gateway Developer portal ① サ ブ ス クリプ シ ョン と API キ ー の 発 行 ② アプリ開発とキーの組み込み ③ API キ ー を 使 用 した 呼 び 出 し (micro)services ④ バ ックエ ンド API が 呼 び 出 され る
26. API 発行と利用 - セルフサービス型 アプリ開発者は開発者ポータルにサインアップ/サインインする ことで利用可能な API を発見、試用してアプリに組み込む 開発者が自身で API の説明を確認、テストアプリ、サンプルコード、キー管理などを利用する ことができる 27 開発者ポータル自体は API ゲートウェイ部分とは独立した Web アプリケーション
27. API 発行と利用 - セルフサービス型 サブスクリプション発行を開発者セルフサービスにしたい場合 は、少なくとも以下の考慮が必要になる 開発者ポータルの有効化 開発者（ユーザー）の認証方式の設定 各ユーザーのグループメンバーシップの管理 28
28. API 発行と利用 - セルフサービス型 アプリ開発者となる APIM の「ユーザー」を認証するための ID プロバイダーを設定する 既定で設定されている「ユーザー名とパスワード」プロバイダーは、API Management 自体 でユーザー管理と認証を行うためのモノ IDP として Azure Active Directory や Azure Active Directory B2C を使用すること で認証自体は外部委任することができる その他のソーシャル ＩＤＰ も利用可能だが現在は非推奨となっている 29
29. API 発行と利用 - セルフサービス型 各ユーザーが実際にどの製品を利用できるかはグループメン バーシップによって判定される 認証ユーザーは既定のグループへ自動的に参加する Administrators : APIM 作成時に指定したメールアドレス、ないしは Azure Portal から明示的に追加 Developerｓ : 開発者ポータルで「認証された」ユーザーが既定で所属するグループ Ｇｕｅｓｔｓ : 開発者ポータルで「認証されていない」ユーザーが既定で所属するグループ きめ細かなアクセス制御を行いたい場合はカスタムグループを作成する APIM で作成したグループ : 認証されたユーザーを明示的に登録・削除して管理したい場合に利用する Azure AD グループ : Azure AD 上で管理されたグループにアクセス権を割り当てたい場合に利用する 30 インターネットに公開してお試し 利用できる製品 > Guests グループ 認証されたユーザーであれば利 用してよい製品 > Developers グループ 特定の許可されたユーザーに しか利用させたくない製品 > カスタムグループ 製品に対するグループアクセス許可の割り当ての例
30. API 運用 Azure Portal から 各種メトリックや統計情報を確認 Ｃｌａｓｓｉｃ の場合は既定の設定で表示可能だが、ｖ２ の場合は ＬｏｇＡｎａｌｙｔｉｃｓ Ｗｏｒｋｓｐａｃｅ へのログ転送（診断設定）が必要になる 31
31. ＡＰＩ 運用 All APIｓ や個別の ＡＰＩ レベルで Ａｐｐｌｉｃａｔｉｏｎ Ｉｎｓｉｇｈｔｓ や Ｌｏｇ Ａｎａｌｙｔｉｃｓ で収集するデータのカスタマイズを行う 例）既定では収集されない ＨＴＴＰ Ｈｅａｄｅｒ や Ｂｏｄｙ を含める等 32
32. ＡＰＩ 運用 Application Insights ロガーを設定すると、アプリケーション マップ等の高度な分析が利用可能になる 33 Application Insights Kusto クエリ
33. よく利用する機能 34
34. API の更新と変更管理 中継点となる API の変更は影響が大きいため、新旧を並行 稼働させることでサービス停止や混乱を防ぐ 非互換が発生する重大な仕様変更を伴う場合にはバージョン管理を行う Azure API Management のバージョン 互換性が保たれるバクフィックスやバックエンドの更改などにはリビジョン管理を行う API Management のリビジョン 35 クライアント v１ Rev1 （モック応答） Rev2 （実 API 呼出） API Managemnt api-version=v1 現在の リビジョン 正式版のAPI v１ Rev1 （モック応答） Rev2 （実 API 呼出） api-version=v1 正式版のAPI Before After 自動切換え V1 向け実装 API 仕様 V2 api-version = v１ api-version = v2 V２ 向け実装 Client V1 Client V2 Supportable Supportable Preview V1 V2
35. API リビジョンの更新 いきなり API 定義を書き換えるのではなく、新規リビジョンの 作成 > 新しいリビジョンの定義を修正 > 新しいリビジョンを アクティブにする（make current）の流れで作業する 36 リビジョン２を追加しても まだ１が Current リビジョン２の定義を修正する （１を修正すると利用中のユーザーに影 響が出るため） API 実装にルーティング リビジョン２の定義が終わってテス トしたら ２ を Current にする
36. API バージョンアップ 最初の API 作成時にバージョニングを有効にすること 新バージョンが追加されると独立した API 定義として管理される 呼び出し側はパス、クエリ文字列、ヘッダーにバージョンを明示して呼び分けることができる 37 同一 API の別バージョン
37. 複数環境の API Management 安定した保守・運用を行うためには複数の APIM をホストすること が多く、環境依存設定の切り分けが重要 開発環境で作成した API / Operation / Policy はテスト環境や本番環境に同一のものを反映 バックエンド API の URL やその認証情報など各種の環境依存の内容は後述の名前付きの値や バックエンド機能で管理する 38 開発 テスト 本番 API / Operation / Policy API / Operation / Policy API / Operation / Policy 名前付きの値 / バックエンド 名前付きの値 / バックエンド 名前付きの値 / バックエンド Replicaiton Replicaiton ※ 各環境間のレプリケーションは Azure の IaC 機能である ARM/Bicep を活用したり OSS として開発されている AIOps Toolkit を使用するとよい（詳細は割愛）
38. バックエンド 実体となる API をカプセル化して扱うための機能 ポリシー内で扱う際にバックエンド URL や認証情報を切り離して管理することができる サーキットブレーカー機能や負荷分散プールとしての機能も利用可能 set-backend-service ポリシーを利用して動的に切り替えることができる forward-request の転送先として利用される 39 <set-backend-service backend-id="azure-openai-openai-endpoint" /> ポリシーからは名前で参照 URLや認証情報などを管理 onpremise -backend cloud -backend API + Operation Policy URL やキーなど環境依存値を ハードコードしない
39. 名前付きの値 Key-Value 型のデータストアとしてポリシーやバックエンドから参 照することができる 環境固有値などを切り出して管理することで、ポリシーやバックエンドをデプロイ環境にあわせて調整 することができる 固定値だけでなく Azure KeyVault で管理された値の参照やポリシー式を登録することも可能 40 <!-- Policy で API Header を名前付きの値に設定する--> <set-header name="x-backend-envname" exists-action="append"> <value>{{environment-name}}</value> </set-header> バックエンドから 名前付きの値を参照
40. Restore-AzApiManagement ` -ResourceGroupName $apiManagementResourceGroup ` -Name $apiManagementName ` -StorageContext $storageContext ` -SourceContainerName $containerName ` -SourceBlobName $blobName Backup-AzApiManagement ` -ResourceGroupName $apiManagementResourceGroup -Name $apiManagementName ` -StorageContext $storageContext ` -TargetContainerName $containerName ` -TargetBlobName $blobName バックアップとリストア 定期的に APIM のバックアップを取っておくことで、ロールバックだ けでなく災害対策にも利用できる 災害時にバックアップデータから APIM を新規構築するためダウンタイムは発生するが、Basic や Standard でも可能なため Premium が必要なマルチAZ やマルチリージョン構成より安価 ユーザーやサブスクリプションなどのランタイムデータも復元するため、開発環境からテスト環境への 設定のレプリケートなどの目的には向いていない またバックアップされない情報など一部制約があるため、詳細はドキュメントを参照 41 Backup Restore Restore 本番環境 （オリジナル） 災害対策環境 クライアント バックエンド API ディザスター リカバリーのために Azure API Management のインスタンスのバックアップと復元を行う APIM の URL が変わるため、クライアント 側はDNS 切り替えや証明書などの考慮は 事前に必要 バックエンド API 側も同様に被災している 場合は、リクエスト転送先の切り替え等の 考慮が必要
41. API Management の可観測性 APIM は多数の API とクライアントの集約点になるためログの記 録が重要 Azure Monitor へログ転送しておくことで、柔軟な分析や可視化、アラート通知などが可能になる Log Analytics と Application Insights はその特性に応じて使い分けること 42 Backend API Client API Management リソースログ アクティビティログ メトリック Log Analytics Workspace APIM を経由した通信だけでなく、メトリック や Azure 基盤のアクティビティログなども 集約して記録、分析が可能 Application Insights クライアントやバックエンド API も含めた 分散トレーシングの機能が利用可能 開発者向け 管理者向け メトリックとアクティビティログは設定し なくても Azure Portal から確認可能 だが、長期保管はされないため、診断 設定でログを転送しておくとよい Gateway ログ
42. Log Analytics によるログ記録 Log Analytics を使用する場合は、診断設定でログ転送を指定し たうえで、必要に応じて API 側でログ記録を有効化する API の呼び出しや転送を記録したい場合は All APIｓ か個別の ＡＰＩ スコープで有効化を行う 基盤観点で利用することが多いため Ａｌｌ ＡＰＩs で設定することが多い（全 API に継承される） 43 ログ記録を有効化する ログの転送先を設定 呼び出し・転送を記録したい場合に有効化 Gateway からの ログを記録する
43. Application Insights でのログ記録 APIM のロガーとして Application Insights を登録、必要に応じ て API 側でログ記録を有効化する API の呼び出しや転送を記録したい場合は All APIｓ か個別の ＡＰＩ スコープで有効化を行う API によって分散トレーシングを行いたいバックエンドや開発者が異なることが多く、ログに出力した い項目の要件も異なるため、個別 API レベルでアドホックに設定することが多い 44 ログ記録を有効化し Application Insighs ロガーを指定 ロガーとなる Application Insights を登録（複数可）
44. Application Insights でのログ記録 45 Azure API Management と Azure Application Insights の統合 - Azure API Management | Microsoft Docs
45. Azure Monitor メトリックと正常性 “メトリックエクスプローラー”を使用す ると概要ビューより詳細な分析が可能 “リソース正常性”でサービスが正 常に動作しているか確認 46 API Management でサポートされているメトリック API Management のリソース正常性チェック内容
46. APIM 組み込みの監視と分析機能 下記の ２ 機能は特に設定することなく API Management の作 成直後から利用可能 ※ 従量課金レベルを除く ※ v2 レベルでは API 分析に Azure Monitor が必要 47 API Management の API 分析 様々な観点（時刻、地理的な場所、API、操作、製品、サブスクリプション、ユー ザー、要求）で使用状況やパフォーマンスを分析 問題の診断と解決 APIM で公開された API のトラブルシューティングを支援するインテリ ジェントな対話型エクスペリエンス
47. 高度な分析の例 診断設定で各種ログをEvent Hub にエクスポートすることで カスタムソリューションを構築することも可能 48 Data plane Gateway Apps on devices (micro)services Event Hub Stream Analytics Power BI Machine Learning SQL Database Hadoop Storage
48. Security 49
49. データプレーンのセキュリティ 50 Developer portal Gateway Admin console Key OAuth 2 & OpenID Connect Client certificate IP filter External authorizer (custom) Rate limits and quotas “Downstream” “Upstream” Key Mutual certificate OAuth 2 & OpenID Connect* HTTP Basic IP filter Network security (VNET)
50. 仮想ネットワークへのインジェクション 外部モード ゲートウェイのバックエンドから VNET 内やオンプレ ミスリソースへの閉域ネットワークアクセスが可能に 開発者ポータルやゲートウェイのフロントエンドは変 わらずパブリックインターネットからアクセスが可能 内部モード API Management のすべてのサービスエンドポイント が VNET 内からのみアクセス可能に（独自 DNS 構成 が必要） ゲートウェイのフロントエンド閉域化されてしまうため、 Azure Portal からの API テストが使用不能になる 51 外部・内部 VNET モードは Premium/Developer のみで利用可能
51. 受信トラフィックの Private Endpoint API Gateway の受信用エンドポイントを VNET 内に設置するこ とでアクセス元のネットワークを制限する Developer | Basic | Standard | Premium で利用可能（Consumption や V2 では利用不可） API Management のバックエンド側（送信側）は Public アドレス空間での通信になることに注意 52
52. 送信トラフィックの VNET 統合 バックエンド側への送信トラフィックを VNET 内にルーティン グして閉域接続を可能にする Standard ｖ２ 価格レベルでのみ利用可能 受信側は Public のまま（Private Endpoint 非対応）であることに注意 53
53. セルフホステッド ゲートウェイ API Gateway を任意の場所でホストすることで、トラフィック フローを最適化し、セキュリティとコンプライアンス要件に対応 Gateway へのイングレス／エグレス通信共に Azure を経由する必要がない ゲートウェイは Docker コンテナーイメージと して提供され、オンプレ Kubernetes 等の 各種環境で実行可能 マネージドゲートウェイと比較すると一部の 機能に制限がある 54 Developer portal Gateway Admin portal Self-hosted Gateway Client App Backend API 管理プレーンへの通信 : 443 （構成情報、ハートビート、ログ等） https://docs.microsoft.com/ja-jp/azure/api- management/self-hosted-gateway-overview
54. IP アドレス制限 VNET 統合を行わない場合には IP アドレス制限を検討する イングレス制御 ： inbound ポリシーセクションで ip-filter ポリシーを利用する エグレス制御 ： バックエンド API の Firewall で API-M の IP のみ許可する 55 Client Backend API API Gateway Ingress Egress Ｃｌｉｅｎｔ の送信 ＩＰ を登録 API Management の送信 IP を登録 ※ 従量課金および V2 プランではサービスインスタンス専用のパブリック IP がないため設定できない Inbound ポリシー Azure API Management サービスの IP アドレ ス | Microsoft Learn
55. フロントエンド側の認証保護 クライアント証明書 クライアント証明書を要求するように構成し、validate- client-certificate ポリシーで提示された証明書を 検証する JSON Web Token の検証 validate-jwt ポリシーで提示されたトークンが必要な 条件を満たしているか検証する クライアントは事前に IDP から必要なトークンを取得し、 HTTP ヘッダーやクエリパラメータで送信する必要が ある 56 Client API Gateway Ingress https://docs.microsoft.com/ja-jp/azure/api-management/api- management-access-restriction-policies
56. フロントエンド側の流量制限 転送率とクォータを元にスロットリング制限をかけることで API を保護することもできる 転送率の制限 ：短期間かつ大量のバーストを防止するために使用する クォータ ：サブスクリプションのレベルに応じた長期間の呼び出し上限を設定する 57 Client API Gateway Ingress <rate-limit-by-key calls="10" renewal-period="60" counter-key="@(context.Request.IpAddress)"/> <quota-by-key calls="10000" bandwidth="40000" renewal-period="2629800" counter-key="@(context.Subscription.Key)" />
57. バックエンド API の認証保護 バックエンド API が対応する認証方式に応じて必要な認証 情報をセットすることができる 基本認証 クライアント証明書認証 Managed ID による Azure AD 認証 58 Egress Backend API API Gateway 証明書認証は API 定義で Backend 指定画面でも設定できる （ポリシーが自動的に追加される） Managed ID は別途有効化しておく
58. バックエンド API の共有キー バックエンド API が呼び出しに API キーを要求する場合は 変換ポリシーを利用して情報を付与する HTTP ヘッダーの設定 クエリ文字列パラメータの設定 59 Egress Backend API API Gateway
59. 管理プレーンと開発者ポータルのセキュリティ 60 Developer portal Gateway Admin console Username/Password Internet identity providers: Microsoft account Google account Facebook account Twitter account Delegated (custom) Azure AD Azure AD B2C App developers (use APIs) API providers Azure AD Role Based Access Control
60. 開発者ポータルのユーザー認証 開発者ポータルにアクセスできるユーザーを認証することで API の不正利用を防ぐ 既定では「ユーザー名とパスワード」によるユーザー管理が有効になっているが、Azure AD や Azure AD B2C といった外部の Ｉｄｐ による認証も可能 自身が管理する Ｗｅｂ サイトに認証を「委任」することも可能（対応する各種エンドポイントを 用意する必要がある） 61 Developer portal App developers (use APIs) Idp サインイン トークン トークン
61. 開発者ポータルのアクセス制御 認証された開発者ポータルのユーザーは、割り当てられたグループ に関連付けられた「製品」を利用することが出来る 製品をグループに関連付けておくことで、開発者ポータルでアクセス可能な製品が参照できる 開発者は各製品の利用に必要な「API キー」を自身で発行することができる（サブスクリプション） 62 ↑製品とグループの関連付け グループへのメンバー追加→ （Azure Portal） 開発者ポータルから サブスクリプションとキーを確認
62. 開発者ポータルのアクセス制御 開発者は自身の所属する“グループ” に割り当てられた製品 および API を利用できる 未認証ユーザー Guests グループに割り当てられた製品が自動的に表示される 匿名ユーザーを許可したくない場合はサインインページにリダイレクトすることも出来る 認証ユーザー 自動的に参加する Developers グループに割り当てられた製品が表示される 各 API を表示するユーザーを絞り込みたい場合は、製品に対してカスタムグループを割り当てる 63 Product Group User Subscription 製品にグループを追加する API グループにユーザーを追加する
63. 管理プレーンの保護 Azure Portal や ARM API を利用する管理操作のアクセス 制御には Azure RBAC を利用する API Management が所属するサブスクリプションの Azure AD ユーザーに対して、必要な ロールが割り当てられている場合に管理操作が可能 下記は API Management 専用に設計されたロールだが、これ以外にも所有者や共同作 成者ロールもアクセス権を持っている 64 Role 読み取りアクセス[1] 書き込みアクセス[2] サービスの作成、削除、 スケーリング、VPN、カ スタム ドメインの構成 以前のパブリッ シャー ポータルへ のアクセス 説明 API Management Service Contributor ✓ ✓ ✓ ✓ スーパー ユーザー。 API Management のサービスとエンティ ティ (API やポリシーなど) への完全な CRUD アクセス権があ る。 以前のパブリッシャー ポータルにアクセスできる。 API Management サービス リーダー ✓ API Management のサービスとエンティティへの読み取り専 用アクセスがある。 API Management サービス オペレーター ✓ ✓ API Management サービスは管理できるが、エンティティの管 理はできない。 [1] API Management サービスとエンティティ (API やポリシーなど) への読み取りアクセス [2] 次の操作以外の API Management サービスとエンティティへの書き込みアクセス: インスタンスの作成、削除、およびスケーリング、VPN 構成、カスタム ドメインのセットアップ https://docs.microsoft.com/ja-jp/azure/api-management/api-management-role-based-access-control
64. 利用料と可用性 65
65. 価格レベルに基づく機能比較 66 https://docs.microsoft.com/ja-jp/azure/api- management/api-management-features 機能 従量課金 開発者 基本 Basic v2 Standard Standard v2 Premium Microsoft Entra 統合 1 いいえ はい いいえ はい はい はい はい 仮想ネットワーク (VNet) インジェクションのサポート いいえ はい いいえ いいえ いいえ いいえ はい 受信接続用のプライベート エンドポイントのサポート いいえ はい はい いいえ はい いいえ はい 仮想ネットワークの外部統合のサポート いいえ いいえ いいえ いいえ いいえ はい いいえ 複数リージョンのデプロイ いいえ いいえ いいえ いいえ いいえ いいえ はい 可用性ゾーン いいえ いいえ いいえ いいえ いいえ いいえ はい ゲートウェイ用の複数カスタム ドメイン名 いいえ はい いいえ いいえ いいえ いいえ はい 開発者ポータル2 いいえ はい はい はい はい はい はい ビルトイン キャッシュ いいえ はい はい はい はい はい はい 外部キャッシュ はい はい はい はい はい はい はい 自動スケール いいえ いいえ はい いいえ はい いいえ はい API 分析 いいえ はい はい はい はい はい はい セルフホステッド ゲートウェイ3 いいえ はい いいえ いいえ いいえ いいえ はい ワークスペース いいえ いいえ いいえ いいえ いいえ いいえ はい TLS の設定 はい はい はい はい はい はい はい クライアント証明書認証 はい はい はい はい はい はい はい ポリシー4 はい はい はい はい はい はい はい 資格情報マネージャー はい はい はい はい はい はい はい バックアップと復元 いいえ はい はい いいえ はい いいえ はい Git による管理 いいえ はい はい いいえ はい いいえ はい ダイレクト管理 API いいえ はい はい いいえ はい いいえ はい Azure Monitor のメトリック はい はい はい はい はい はい はい Azure Monitor と Log Analytics の要求ログ いいえ はい はい はい はい はい はい Application Insights の要求ログ はい はい はい はい はい はい はい 静的 IP いいえ はい はい いいえ はい いいえ はい
66. 利用料とSLA 最新の価格表やSLA の諸条件など詳細に関しては最新のド キュメントを参照 API Management の価格 | Microsoft Azure Licensing Documents (microsoft.com) 67 機能 従量課金 Developer Basic Standard Premium Basic V2 Standard V2 目的 API Management サー ビスの軽量型でサーバー レスのバージョン、実行ごと に課金 非運用ユースケースと 評価 エントリレベルの 運用ユース ケー ス 中容量の運用 ユースケース 大容量またはエンター プライズ運用のユース ケース チームとプロ ジェクトの API 管理 組織の API プログ ラムを起動し、起動 に乗るにつれてス ケーリングする SLA 99.95% N/A 99.95% 99.95% 99.99% （複数リージョンまた は複数ゾーンの場合） 99.95% 99.95% 最大スケールアウト N/A 1 2 4 12 / region 10 10 料金（基本ユニット） N/A $48.04/月 $147.17/月 $686.72/月 $2,795.17/月 $150.01/月 $700/月 料金（追加ユニット） N/A N/A $147.17/月 $686.72/月 $1,397.59/月 $150.01/月 $500/月 料金（API 要求 – 無償） 100万 まで N/A N/A N/A N/A 1000万 5000万 料金（API 要求 – 有償） $0.0425 （1万回あたり） N/A N/A N/A N/A $3 (100万回) $2.50 (100万回)
67. クラシックレベルのアップグレードとスケーリング 最大ユニット数について 価格レベルに応じて最大スケールアウトが可能なユニット数が決まる Developer ≦ 1, Basic ≦ 2, Standard ≦ 4, Premium ≦ 12/region 各ユニットのキャパシティ 各価格レベルでユニット単位の予測最大スループット（RPS）も異なる Developer ≦ 500, Basic ≦ 1000, Standard ≦ 2500, Premium ≦ 4000 自動スケール可能 Basic/Standard/Premium はメトリックベースの自動スケールが可能 従量課金はそもそもユニットという概念がなく既定で自動スケール構成 アップグレード（ダウングレード） Developer、Basic、Standard、Premium 間は互換性があるため変更が可能 サポートする機能に差異があるため、特にダウングレード時には利用中の機能セットに注意 69
68. Ｖ２ レベルのアップグレードとスケーリング 最大ユニット数について Basic v2/Standard v2 ともに最大 10 ユニットまでスケールアウトが可能 各ユニットのキャパシティ 予測最大スループットは公開されていないため、現状では実測ベースで評価する必要がある 手動スケール 現時点では自動スケールに対応していないため、ユニット数を明示的に指定する必要がある アップグレード（ダウングレード） Basic v2/Standard v2 間はアップグレード/ダウングレードが可能 70
69. 高可用性 Premium 価格レベルではゾーン冗長および複数リージョン デプロイを適用することで 99.99% の SLA が提供される 71 Region Zone 2 Zone 3 Zone 1 Availability Availability Availability Datacenter Datacenter Region 1 Region 2 Premium 以外は選択したリージョン内 のいずれかの場所に自動的に配置され る（可用性セットベース） Premium でも既定はこの構成 ゾーン冗長を有効にすることで内包する各ユニットを複 数ゾーンに対して分散配置することができる ゲートウェイだけでなく管理 API や開発者ポータルなど も冗長化され、ゾーン障害に対する回復性が向上する 複数リージョン配置を有効にすることで広域災害およびグローバル 負荷分散に対応し、リージョンの制限を超えたスケールアウトが可能 API は単一のURLでホストされるが最も近いリージョンに自動的に ルーティングされる セカンダリリージョンに配置されるのはゲートウェイ部分のみ Region 3
70. マルチ AZ/マルチリージョン（併用可能） 複数の可用性ゾーンへの配置 ゲートウェイ、管理プレーン、開発者ポータルのす べてが AZ 冗長配置される 使用するゾーン数と同じかその倍数となるユニッ ト数を指定する 複数のリージョンへの配置 管理プレーンと開発者ポータルは Primary リー ジョンに、ゲートウェイが複数リージョンに配置 リージョン間は Traffic Manager による負荷分 散が行われる 72 AZ1 AZ２ AZ３ Management Plane User Plane （開発者ポータル） Data Plane（ゲートウェイ） Primary Region Secandary Region Management Plane User Plane Data Plane（ゲートウェイ） Traffic Manager 最寄りのリージョンへルーティング
71. Appendix A Reference 73
72. リファレンス 公式ドキュメント API Management のドキュメント API Management の価格 API Management の SLA トレーニングコンテンツ（Microsoft Learn） Azure API Management の概要 API Management の詳細 Azure ラーニング パスでの API 統合の設計 非公式 Azure Api Management 俺的マニュアル 2020年3月版 (slideshare.net) aka.ms/apimlove | api-management-resources (azure.github.io) 74
73. Appendix B IaC による APIM 構成の概要 75
74. オブジェクト モデル APIM の多くの「設定」は実際には Azure リソースであり、ARM / Bicep テンプレートを使用して構成することができる Microsoft.ApiManagement 名前空間 内のオブジェクトとして定義されている API / Operation は OpenAPI 仕様として、Policy は XML ドキュメントとして定義しておくことで ARM/Bicep に読み込ことができる ｓervice namedValues logger backends 1:N apis 1:N 1:N 1:N diagnostics operations 1:N 1:1 policy policy policy 1:1 1:1 1:1 ※ Versioning が無い場合の大まかな構造 OpenApi (json) All APIs policy (xml) Api policy (xml) Operation policy (xml) API Revision 単位で作成 読み込むドキュメント （Azure リソースではない） これらのリソースは各リソースから ”名前”で参照するため、直接の 依存関係がない
75. API Management の例 77 Microsoft.ApiManagement/service resource apiman 'Microsoft.ApiManagement/service@2023-03-01-preview' = { name: 'your-apimanagement-name' location: 'japaneast' sku: { name: 'Developer' capacity: 1 } properties: { publisherName: 'your-publisher-name' publisherEmail: 'publisher-mail@example.com' } }
76. 名前付きの値の例 78 Microsoft.ApiManagement/service/namedValues resource namedValue1 'Microsoft.ApiManagement/service/namedValues@2023-03-01-preview' = { parent: apiman name: 'backend-url' properties: { displayName: 'backend-apikey' value: 'hogehogehoge' secret: true } } 機微情報なので実際には テキストで指定しないが例として
77. バックエンドの例 79 resource backend1 'Microsoft.ApiManagement/service/backends@2023-03-01-preview' = { parent: apiman name: 'backend-name' properties: { title: 'backend-title' description: 'description of this backend' protocol: 'http' url: 'https://yourbackend.example.com/api' credentials: { header: { 'api-key': ['{{backend-apikey}}'] } query: { 'environment-name': ['{{backend-environment-name}}'] } } } } Microsoft.ApiManagement/service/backends ポリシーの場合と同様に 名前付きの値を参照できている
78. ロガーの例 80 resource ailogger 'Microsoft.ApiManagement/service/loggers@2023-03-01-preview' = { parent: apiman name: 'your-logger-name' properties: { loggerType: 'applicationInsights' resourceId: appinsights.id credentials: { instrumentationKey: appinsights.properties.InstrumentationKey } } } resource appinsights 'Microsoft.Insights/components@2020-02-02' existing = { name: 'your-application-insights-name' } Microsoft.ApiManagement/service/backends
79. API の例 Microsoft.ApiManagement/service/apis resource echoApi 'Microsoft.ApiManagement/service/apis@2023-03-01-preview' = { parent: apim name: 'Echo API' properties: { path: 'echo' subscriptionRequired: true protocols: [ 'https' ] type: 'http' serviceUrl: 'https://your-apiendpoint.example.com/echo' subscriptionKeyParameterNames: { header: 'api-key' } format: 'openapi' value: loadTextContent('./echo-api-spec.json') } } 直接ここにハードコードするのではなく OpenAPI 仕様として外部ファイルで定義
80. API レベル Policy と Loggerの例 82 Microsoft.ApiManagement/service/apis/policies resource echoApiPolicy 'Microsoft.ApiManagement/service/apis/policies@2023-03-01-preview' = { parent: echoApi name: 'policy' dependsOn: [ backend1 namedValue1 ] properties: { format: 'rawxml' value: loadTextContent('./operationLevelPolicy. xml') } } resource appinsDiag 'Microsoft.ApiManagement/service/apis/diagnostics@2023-03-01-preview' = { parent: echoApi name: 'applicationinsights' properties: { loggerId: ailogger.id alwaysLog: 'allErrors' logClientIp: true verbosity: 'verbose' sampling: { percentage: 100 samplingType: 'fixed' } } } policy 内でバックエンドや名前付きの値を 参照している場合には明示的に依存関係を 設定することでデプロイ順を制御 ポリシードキュメントを直接ハードコード するのではなく外部ファイルで定義 APIM レベルで登録した ロガーを参照
81. Operation と Policy の例 83 Microsoft.ApiManagement/service/apis/operations // 各 Operation は OpenAPI 仕様として apis で定義されているため、ここでは参照して取得 resource operation 'Microsoft.ApiManagement/service/apis/operations@2023-03-01-preview' existing = { parent: openaiApi name: 'Chat_Completionis_Create' resource policy 'policies' = { name: 'policy' dependsOn: [ backend1 namedValue1 ] properties: { format: 'rawxml' value: loadTextContent('./operationLevelPolicy.xml') } } } 直接ここにハードコードするのではなく 外部ファイルで定義
82. Log Analytics と診断設定 84 resource apimDiag 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' = { name: 'apimanagement-diagnostics' scope: apiman properties: { workspaceId: logAnalytics.id logAnalyticsDestinationType: 'Dedicated' logs: [ { category: 'GatewayLogs' enabled: true } { category: 'WebSocketConnectionLogs' enabled: true } ] metrics: [ { category: 'AllMetrics' enabled: true } ] } } resource logAnalytics 'Microsoft.OperationalInsights/workspaces@2022-10-01' existing = { name: 'your-loganalytics-name' } 診断設定は API Management のプロパティではなく Microsoft.Insights/diagnosticSettings リソースとして作成する
83. Tips : リソースプロパティの確認方法 オブジェクト構造が複雑なため、慣れるまでは Portal 上で設 定したものからエクスポートして確認するとよい トップレベルリソースは リソースエクスプローラ で確認しやすいがサブリソースは難しい サブリソースの ID のフォーマットは以下のようになっている /subscriptions/guid/resourceGroups/rgname /providers/Microsoft.ApiManagmeent/service/apimanName /backends/backendName /apis/yourApiName /apis/yourApiName/operations/operationName このリソース ID のルールがわかると以下の操作が可能になる（次項参照） UI 上はナビゲーションできないリソースでも Azure Portal で参照することができる Azure CLI を使用して直接リソースの設定値 JSON をエクスポートすることができる 85 バックエンド、API、Operation リソースの例 リソースの型と名前が交互に記述される構造
84. Tips : リソースプロパティの確認（Azure CLI） リソース ID がわかったら az resource show --ids コマン ドで確認 86 バックエンドから名前付きの値を設定している （ポリシーから参照する場合と同じ）
85. Tips : リソースプロパティの確認（Azure Portal） Azure Portal の URL もリソース ID を使用したパスで指定 すればよい 87 'http-bin' という API の 'get-html' という Operation を確認
86. Microsoft Confidential ◼ 本資料は情報提供のみを目的としており、本資料に記載されている情報は、本資料作成時点でのマイクロソフトの見解を示したものです。状況等の変化により、内容は変更される場合があります。本資料 に特別条件等が提示されている場合、かかる条件等は、貴社との有効な契約を通じて決定されます。それまでは、正式に確定するものではありません。従って、本資料の記載内容とは異なる場合がありま す。また、本資料に記載されている価格はいずれも、別段の表記がない限り、参考価格となります。貴社の最終的な購入価格は、貴社のリセラー様により決定されます。マイクロソフトは、本資料の情報に対 して明示的、黙示的または法的な、いかなる保証も行いません。 © ２０２０ Microsoft Corporation. All rights reserved. Microsoft, Windows, その他本文中に登場した各製品名は、Microsoft Corporation の米国およびその他の国における登録商標または商標です。 その他、記載されている会社名および製品名は、一般に各社の商標です。 88