Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Azure API Management 俺的マニュアル

3,049 views

Published on

2018/11/28 NSStudy No.14にて話した時の資料です。
Azure API Managementを自分用に調べた結果のもので、本当にマニュアルとして作っています。
どなたかのお役に立てば。

Published in: Software
  • Be the first to comment

Azure API Management 俺的マニュアル

  1. 1. Azure API Management 2018/11/28 第14回 NS Study 上坂 貴志(@takashiuesaka) 俺的マニュアル
  2. 2. 自己紹介 上坂貴志 • うえさかたかし Twitter • @takashiuesaka • Facebookは開店休業状態 Microsoft MVP • Microsoft Azure 2015年~ 仕事 • マネージャー、プリセー ルス、エバンジェリスト 最近の興味 • アジャイル、DDD、エン ジニアトレーニング、k8s、 DevOps、.NET Core、 Frontendフレームワーク、 node.js Nextscape Inc. 2
  3. 3. 最近はこんなことしてました 3Nextscape Inc.
  4. 4. NEXTSCAPE 4 HoloLensアプリ作ろう DDDやろう Scrumでやろう! SESやっていないので、自社で開発100%ですよ 只今、PM・エンジニア積極採用中です Nextscape Inc.
  5. 5. Nextscape Inc. 5 今日の内容
  6. 6. API Managementとは What is API Management?
  7. 7. • HTTPベースのAPIを外部に公開する時に必要な仕組みを一通り揃えたPaaSです。 • APIとそれを呼び出すClientとの間に挟み込むようにDeployします。 API Managementとは API (Backend) (Publisher) Client (FrontEnd) (Consumer) API Management Nextscape Inc. 7
  8. 8. • 一般的にAPI公開時に求められる以下のようなシナリオに対応できます。 API Managementとは 外部の開発者に対してAPIごとに使用許可を制御したい APIの使用を無料ユーザー用や有料ユーザーなどに分けて制御したい APIのバージョンを簡単に管理したい 外部の開発者がAPIを呼び出してテストできるページを用意したい • さらにAzure環境ならでは次の要求にも対応できます。 VNETで守られたVMで立てたAPIを外部に公開したい VNET内部だけで公開するAPIに対して上記一般的なシナリオ(バージョン管理やテストページの用意など)に対応したい Nextscape Inc. 8
  9. 9. API Management 全体像 Overview
  10. 10. Developers Guests カスタム Admins API Management 全体像 API Management グループ API サブスクリプション Policy Frontend Backend Api /path https://~ https://<APIM Name>.azure-api.net アクセス制御 開発者(ユーザー) N:N Operations In Out Err Policy N:N 開発者ポータル Nextscape Inc. 10 API (Backend) (Publisher) Client (FrontEnd) (Consumer) 成果物(製品) N:N
  11. 11. Developers Guests カスタム Admins N:N API Management 全体像 API Management サブスクリプション Policy Frontend Backend Api /path https://~ https://<APIM Name>.azure-api.net アクセス制御 開発者(ユーザー) N:N API (Backend) (Publisher) Operations In Out Err Policy N:N 開発者ポータル Client (FrontEnd) (Consumer) Nextscape Inc. 11 API 成果物(製品) グループ API: API Managementから到達できるAPIであればなんでも登録 できる。まずはここへ API を登録するところからスタート。 PolicyではRequest/Response/Errorに対して処理をC#で書 くことができる。
  12. 12. Developers Guests カスタム Admins グループ API Management 全体像 API Management サブスクリプション Policy Frontend Backend Api /path https://~ https://<APIM Name>.azure-api.net アクセス制御 開発者(ユーザー) N:N Operations In Out Err Policy N:N 開発者ポータル Nextscape Inc. 12 API (Backend) (Publisher) Client (FrontEnd) (Consumer) API N:N 成果物(製品/Products): docsでは「成果物」もしくは「製品」と記載されている。 Portalでは「製品」となっているので要注意。 APIに対してアクセス制御を行うのが主な役割。 APIと成果物はN:Nの関係性。APIは複数の成果物に登録がで きる。 成果物(製品)
  13. 13. グループ Developers Guests カスタム Admins API Management 全体像 API Management サブスクリプション Policy Frontend Backend Api /path https://~ https://<APIM Name>.azure-api.net アクセス制御 開発者(ユーザー) N:N Operations In Out Err Policy N:N 開発者ポータル Nextscape Inc. 13 API (Backend) (Publisher) Client (FrontEnd) (Consumer) API グループ: 開発者は複数の(カスタム)グループに所属することができる。 ユーザー登録した開発者は必ずDevelopersグループに所属する。 成果物のアクセス制御にグループを登録することで、そのグ ループに所属する開発者はその成果物を使用することができる ようになる。 グループと成果物はN:Nで紐づけることができる。 成果物(製品) N:N
  14. 14. Developers Guests カスタム Admins N:N グループ API Management 全体像 API Management サブスクリプション Policy Frontend Backend Api /path https://~ https://<APIM Name>.azure-api.net アクセス制御 開発者(ユーザー) N:N Operations In Out Err Policy N:N 開発者ポータル Nextscape Inc. 14 API (Backend) (Publisher) Client (FrontEnd) (Consumer) Policyでできること(やること)の代表格 セキュリティ&アクセス制限 • API キー、JWT トークン、証明書、その他の資格情報を検証 • 使用量クォータとレート制限を適用 • IPアドレスやユーザーIDで接続を制限・スロットリング キャッシュ • Backend APIのResponseをキャッシュ その他 • Request/Reponseログを転送 • 外部サービスをHttpで呼び出し API 成果物(製品)Policy: PolicyはBackend APIへRequestを投げる前後に処理を入れることができる。処理 はC#で実装する。 PolicyはBackend APIが公開する複数の操作(Operation)ごとに設定もできるし、 Backend API全てに共通の設定もできるなど、スコープが4段階ある。 (操作の例: /id) 実に多彩な処理の実装が可能。テンプレートもあるが、外部にReqeustを投げるこ とができるので独自実装を頑張ればかなりのことができる。
  15. 15. Developers Guests カスタム Admins N:N グループ API Management 全体像 API Management サブスクリプション Policy Frontend Backend Api /path https://~ https://<APIM Name>.azure-api.net アクセス制御 開発者(ユーザー) N:N Operations In Out Err Policy N:N 開発者ポータル Nextscape Inc. 15 API (Backend) (Publisher) Client (FrontEnd) (Consumer) API アクセス制御: アクセス制御は成果物を使用できるグループを設定す ることで可能となる。 ここでいうアクセス制御とは、開発者(ユーザー)に 対してのものであることに注意。 Policyによるアクセス制限: 成果物にもPolicyが設定できる。API単位より上の スコープでの設定と思えばOK。 例えば使用量上限があるプランのAPI群を公開し たい場合、そのプラン用の成果物を作成して使用 量クォータによる制限のPolicy実装をここに設定 することになる。 成果物(製品) サブスクリプション: 成果物では、開発者(ユーザー)に対して利用許諾の 申請を求める設定がある。その設定をONにした場合、 開発者&成果物ごとのサブスクリプションキーが発行 され、それをHeaderに入れないとRequestが失敗す る。 (申請を自動承認するか、手動で承認するか選択)
  16. 16. 超基本の使い方 Basic usage of API Management
  17. 17. APIを追加する Nextscape Inc. 17 • Blank APIを選ぶと、自分でOperationを追加する必要がある • 他のやつは定義を読んで自動的にメソッドを追加してくれる(はず) • API作るときは、Swagger入れておくと便利だよってこと
  18. 18. APIを追加したあとの「API」画面 Nextscape Inc. 18 外部からRequestを 受ける入口の設定 バックエンドAPIの 設定 バックエンドAPIへRequest を投げる前のカスタム処理 バックエンドAPIからのResponse を返す前のカスタム処理
  19. 19. 成果物へAPIを登録する どれか選ぶ もしくは事前に作っておく APIを選ぶ Nextscape Inc. 19 • 製品(成果物)メニューからAPIを登録する APIの画面から成果物に登録できるようになれば素敵なんだけどなー
  20. 20. • APIを登録しただけだと動かない! • missing subscription key というエラーが出たときの原因は大抵コレ 成果物へAPIを紐づける Nextscape Inc. 20 GroupA グループ アクセス制御 開発者(ユーザー)成果物(製品)API 既存API 新規API 成果物に紐づけないと、 開発者からは見えない。 自分がAdminsグループに 所属する管理者の場合、 Portalからは見えるが実行 時はエラーになる。 成果物に紐づいていないので実 行するとエラーになる
  21. 21. • 外部ツール使ってもいいけど、APIManagementのテストツールを使ったほうが便利 • 自動的にサブスクリプションキーを入れてくれる • Policy実装時には、このツールのTrace機能が必須(詳しくは「ポリシー」の最後にて) • 設定すれば、外部IDProviderのOAuth2.0, OpenIdConnectのTokenを取得させることもできるので、認証が必須のAPIの設 定確認やPolicyの実装結果を確認する時に重宝する 試しにAPIMを叩く Nextscape Inc. 21 大変残念なことにテストツール の実行履歴が一切保存されない。 Policyの実装時にはちょっと辛い
  22. 22. 認証結果の検証 • Policyにて実装 エラーハンドリング • Policyにて実装 ログの出力 • Policyにて実装 スケーリング • Portal/Powershell/Cliで設 定 バックアップ • Portal/Powershellにて設 定 キャッシュ • Portal/Powershellにて設 定 必要なら追加設定する Nextscape Inc. 22
  23. 23. ポリシー Policy of API Management
  24. 24. • ポリシーはXML形式。4ブロックに分かれている ポリシーの基本形 <policies> <inbound> <!–- Backend APIを叩く前に呼びたい処理 --> <base /> </inbound> <backend> <!–- Policyは1つだけしか実装できない。Backend APIを叩くための Poilicyがデフォルトで実装されている --> <base /> </backend> <outbound> <base /> <!–- Backend APIからのreponseを返す前に呼びたい処理 --> </outbound> <on-error> <base /> </on-error> </policies> Nextscape Inc. 24 詳細は後述 詳細は後述
  25. 25. • C#の実装方法は2つの形式がある。 • どちらも括弧の前に@付ける XMLの属性値にC#で実装していく <set-variable name=“date1" value="@(context.Timestamp.ToString("R"))" /> <set-variable name=“date2" value="@{ var results = DateTime.Now.ToString(“yyyy/MM/dd HH:mm:ss.fffff”); return results; }" /> Nextscape Inc. 25 単文の場合は@() 複文の場合は@{} • ポリシー式で使用できる .NET framework の型は決まっているため、usingは不要 • 保存時に名前空間を解決してくれているっぽい(解決できないとエラーになる) • 言い換えると外部dll を読み込ませることができない(Nugetもできない) っていうかこれラムダ式だわ インテリセンスが効かないんだよね・・・
  26. 26. • Reqeust/Response含めたあらゆる情報はこいつが持っている 暗黙的なオブジェクト context Nextscape Inc. 26 Context Timestamp: DateTime Variables: IReadOnlyDictionary<string, object> Response Request LastError Headers: IReadOnlyDictionary<string, string[]> IpAddress: string Body ※一部抜粋 アクセス日時 <set-variables>でセットされた値を保持 Requestのヘッダー値 Request元のIPAddress RequestのBody
  27. 27. • contextは、docsの › 「ハウツーガイド」 › ポリシーの定義 › ポリシー式 › 「コンテキスト変数」セクション • に情報がある contextの中身を知らないと実装できない Nextscape Inc. 27
  28. 28. • ちょっと見方にコツがいる。 • 例:Requestの情報がほしい • まず、contextから探す。 • context.Requestというプロパティが あるのはわかったが、Requestの型も プロパティもわからない・・・ • Requestでこの画面内を検索する contextの中身を知らないと実装できない Nextscape Inc. 28
  29. 29. • context.Requestという項目が見つかった。 • このようにすべての情報はこの画面内にあるので検索して探していく contextの中身を知らないと実装できない • さらにここからUrlの型であるIUrlを検索してみると・・・ Nextscape Inc. 29
  30. 30. • IUrlの情報を得ることができる。 • context.Request.Url.Path と書くことで、リクエスト時のURLを取得できるこ とがわかった • プロパティ名は大文字小文字区別する(Case-Sensitive) contextの中身を知らないと実装できない Nextscape Inc. 30
  31. 31. • サブスクリプションごとに指定期間あたりの呼び出しレートを指定数に制限 利用を制限するポリシー <inbound> <rate-limit calls="5“ renewal-period="60" /> <base /> </inbound> Nextscape Inc. 31 <inbound> <quota calls="100“ bandwidth="40000“ renewal-period="604800" /> <base /> </inbound> • サブスクリプションごとに呼び出し回数と帯域幅クォータの両方またはそのどちらかで制限 KBytes Seconds 1分に5回まで 1週間に100回、 もしくは 40,000KBまで
  32. 32. • キーごとに指定期間あたりの呼び出しレートを指定数に制限 利用を制限するポリシー <inbound> <rate-limit-by-key calls=“5” renewal-period=“60“ counter-key=“@(context.Request.IpAddress)” /> <base /> </inbound> Nextscape Inc. 32 <inbound> <quota calls=“100“ bandwidth=“40000“ renewal-period=“604800” counter-key=“@(context.Request.IpAddress)” /> <base /> </inbound> • サブスクリプションごとに呼び出し回数と帯域幅クォータの両方またはそのどちらかで制限 IPAddress毎に1 分に5回まで IPAddress毎に 1週間に100回、 もしくは 40,000KBまで counter-keyへのセットは文字列なんでもOK
  33. 33. • オブジェクトをディクショナリへ格納する • 何かしらの処理の結果を格納する時に使う set-variablesは多用する Nextscape Inc. 33 <set-variable name="putDate“ value="@(context.Timestamp.ToString("R"))" /> • ディクショナリはcontext.Variables : IReadOnlyDictionary<string, object> • オブジェクトの取り出し方(GenericsではないのでCast必要) • (cast)context.Variables[“keyName”] putDateはディク ショナリのKey名
  34. 34. • 同期リクエストの場合は<send-request> • Responseを取得できる • 非同期リクエストの場合は< send-request-one-way > • Responseは取得できない 外部へリクエストを投げるポリシー • <send-request>のResponseは、指定した変数名でcontext.Variablesディク ショナリに格納される <send-request mode="new" response-variable-name="testResponse" timeout="5" ignore- error="true"> ・・・ </send-request> Nextscape Inc. 34
  35. 35. • Blob SDKが使えないのでREST Apiで実装 • ログを書く処理は非同期にしたいので、 send-request-one-way使用したい • でもエラーでまくって辛かった。どうやってデバッグするか悩んだ • 編み出したやり方は以下 • まずはsend-requestで実装。 • send-reqeustにはresponseを変数に入れる機能がある • responseは、IReseponseクラス。 • responseの中身を見るために、set-variableの実行結果をTraceで見ることに(詳しくはこの後) 追加Blobにログを書くPolicy作ってみた <set-variable name="test" value="@{ var hoge = ((IResponse)context.Variables["testResponse"]).Body.As<string>(); return hoge; }" /> <send-request mode="new" response-variable-name="testResponse" timeout="5" ignore- error="true"> ・・・ </send-request> Nextscape Inc. 35 responseを格納する変数 変数値をTraceで表示させるために意味なく 他の変数にセットする
  36. 36. • これを埋めていく 追加Blobにログを書くPolicy作ってみた <inbound> <base /> <set-variable name="version" value="@("2015-04-05")" /> <set-variable name="putDate" value="@(context.Timestamp.ToString("R"))" /> <set-variable name="logData" value="@{ // ログに出力する内容を作る return something; }" /> <set-variable name="authorizationHeader" value="@{ // BlobのBearer Authorizationヘッダーを作る return authorizationHeader; }" /> <send-one-way-request mode="new"> // 非同期のリクエストを投げる </send-one-way-request> </inbound> Nextscape Inc. 36
  37. 37. • 非同期のリクエストを投げる実装(他は省略) 追加Blobにログを書くPolicy作ってみた <send-one-way-request mode="new"> <set-url>https://{{logstorageName}}.blob.core.windows.net/test/append- blob.log?comp=appendblock</set-url> <set-method>PUT</set-method> <set-header name="x-ms-version" exists-action="override"> <value>@((string)context.Variables["version"])</value> </set-header> <set-header name="x-ms-date" exists-action="override"> <value>@((string)context.Variables["putDate"])</value> </set-header> <set-header name="Authorization" exists-action="override"> <value>@((string)context.Variables["authorizationHeader"])</value> </set-header> <set-body>@((string)context.Variables["logData"])</set-body> </send-one-way-request> Nextscape Inc. 37
  38. 38. • テストツールのTraceを見れば、リクエスト先が返したエラー情報が見え る。 • Ocp-Apim-Traceヘッダにtrueという値を入れておく必要があるが、デフォルトで設 定済みなのであまり気にしなくて大丈夫 Policyのデバッグ方法 Nextscape Inc. 38 デフォルトはMessageタブが 表示されているので、Trace に切り替える この例では、<set-varialble>に設定されたポ リシー式を評価した(実行した)結果を表 示している。
  39. 39. Globalレベル(API の All APIsに設定する) 成果物レベル(製品) API レベル(API の All Operationsに設定する) 各Operationsレベル ポリシーには階層がある • 上から順に評価される。 Nextscape Inc. 39
  40. 40. Globalレベル 成果物レベル APIレベル 各Operationsレベル ポリシーには階層がある • 上位のPolicyは<base />と記載してある箇所に適用される • <base />を消せば、上位のPolicyは無視したことになる Nextscape Inc. 40 <policies> <inbound> <base /> <authentication-certificate thumbprint="3B262F5910138…" /> </inbound> <backend> <base /> </backend> <outbound> <base /> </outbound> <on-error> <base /> </on-error> </policies> • この実装が API レベルにされている場合、<inbound>の<base />はGlobalと成 果物レベルの<inbound>の処理を意味している
  41. 41. • <backend>だけはデフォルトでグローバルレベルに<forward-request>が実装 されている。こいつがBackend Apiを呼び出すタグ。 <backend>について Nextscape Inc. 41 成果物、API、Operationsの全てのレ ベルのデフォルト実装の<backend>の <base />は、削除するとBackend APIが 呼び出されなくなるので注意してね Operationsレベルの例 グローバルレベルの例
  42. 42. • <backend>には1つだけしかPolicyを実装できない制約がある! <backend>について Nextscape Inc. 42 <backend> <retry condition="@(context.Response.StatusCode == 500)" count="3" interval="1"> <forward-request /> </retry> </backend> <backend> <base /> <retry condition="@(context.Response.StatusCode == 500)" count="3" interval="1"> </retry> </backend> エラーとなってしまう例 入れ子にして回避 上位スコープに <forward-request /> が設定されているため必要 <base />を削除
  43. 43. • Visual Studio Code用のスニペットならある・・・けど使えないかな • https://github.com/Azure/api-management-policy-snippets ポリシーの素敵なエディタはないのか Nextscape Inc. 43
  44. 44. 開発者とグループ Developers and Group
  45. 45. 開発者とグループ • グループは成果物とN:Nで紐づけることで開発者へのAPI公開を制御する グループ アクセス制御 成果物(製品) アクセス制御 GroupA GroupB API API API API API 開発者 全部のAPI使用可 下2つのAPIのみ 使用可 Nextscape Inc. 45
  46. 46. 開発者とグループ • デフォルトで用意されているグループは3つ • Administrators, Develpers, Guests • 開発者を新規追加すると、デフォルトでDevelopersグループ所属になる Nextscape Inc. 46 開発者(ユーザー) Developers Guests Admins デフォルトグループ GroupA GroupB カスタムグループ 開発者をPortalから追加しても、開発者 ポータルから開発者自身がサインアップ しても、必ずDevelpersグループの所属に なる
  47. 47. Addボタンがない! 開発者とグループ • あれ、Admin, Guestへのユーザー追加はどうやるのか? • Powershellなら追加できるっていう訳じゃなかった Nextscape Inc. 47
  48. 48. • 共同作成者以上の権限を持つAzureユーザーは自動的に全員Adminグループに紐づけられる • Adminsグループは新規作成の成果物のアクセス制御に自動的に登録される 開発者とグループ グループ アクセス制御 開発者(ユーザー)成果物(製品)API API アクセス制御 Developers Guests Admins デフォルトグループ Azure ユーザー APIM作成者 APIM共同作成者 GroupA GroupB カスタムグループ 自動的に紐づけられる Azureユーザーが紐づける Nextscape Inc. 48 • Guestsグループはユーザー登録をしていない匿名ユーザーが 暗黙的に所属するグループ (登録前にお試しに使ってもらいたい場合などはGuestsグ ループに紐づける=登録しない) API API API
  49. 49. API Manegement Role別機能差 APIM作成者 or APIM 共同作成者 APIM Operator Role APIM Reader Role Portal フル権限 参照のみ。変更設定できるのは スケールアップ・ダウン、SSL、 カスタムドメインの設定ぐらい メトリックス参照で きるぐらい。その他 は参照すらできない 開発者ポータル フル権限 × × 所属Group Administrator Guest Guest • APIMの作成者、またはAPIM 共同作成者ロール の権限があるAzureユーザーは、暗黙的に Administratorグループに所属する(共同作成者 は画面にユーザーとしては表示されない) • APIM Service Reader Role, Operator Roleの権限を もつAzureユーザー、もしくはユーザー登録を していない(認証していない)場合は暗黙的 にGuestグループに所属する Nextscape Inc. 49
  50. 50. • カスタムグループへの開発者の登録はPortalで管理者が行う以外の手段がない • こんな設定にしてあったら、自動的に登録してくれないのかな? カスタムグループへの開発者の登録は手動だけ カスタムサブスクリプション アクセス制御Policy 開発者ポータル 成果物(製品) グループ Developers 1.サブスク申請が 承認されたら 2.カスタムグループに自 動的に登録されないのか1 2 Nextscape Inc. 50 • 承認が必要な成果物を作る • 成果物に対してカスタムグループを紐づけておく • 開発者ポータルからこの成果物に対して サブスクリプション申請 • Portalからサブスクリプションを承認 • 紐づいたカスタムグループにユーザが登録されるか 試すならこんな手順
  51. 51. 試してみた Nextscape Inc. 51 • 承認が必要な成果物を作る • 成果物に対してカスタムグループを紐づけておく • 開発者ポータルからこの成果物に対して サブスクリプション申請 • Portalからサブスクリプションを承認 • 紐づいたカスタムグループにユーザが登録されるか
  52. 52. 試してみた Nextscape Inc. 52 • 承認が必要な成果物を作る • 成果物に対してカスタムグループを紐づけておく • 開発者ポータルからこの成果物に対して サブスクリプション申請 • Portalからサブスクリプションを承認 • 紐づいたカスタムグループにユーザが登録されるか Developerグループも紐づけておかないと、開発 者ポータルに成果物が表示されない
  53. 53. 試してみた Nextscape Inc. 53 • 承認が必要な成果物を作る • 成果物に対してカスタムグループを紐づけておく • 開発者ポータルからこの成果物に対して サブスクリプション申請 • Portalからサブスクリプションを承認 • 紐づいたカスタムグループにユーザが登録されるか
  54. 54. • 開発者ポータルで申請中になったことを確認 試してみた Nextscape Inc. 54
  55. 55. 試してみた Nextscape Inc. 55 • 承認が必要な成果物を作る • 成果物に対してカスタムグループを紐づけておく • 開発者ポータルからこの成果物に対して サブスクリプション申請 • Portalからサブスクリプションを承認 • 紐づいたカスタムグループにユーザが登録されるか
  56. 56. • 申請が許可されてSucscription Keyが発行された 試してみた Nextscape Inc. 56
  57. 57. 試してみた Nextscape Inc. 57 • 承認が必要な成果物を作る • 成果物に対してカスタムグループを紐づけておく • 開発者ポータルからこの成果物に対して サブスクリプション申請 • Portalからサブスクリプションを承認 • 紐づいたカスタムグループにユーザが登録されるか 追加されなかった・・・残念
  58. 58. サブスクリプション Subscription
  59. 59. • 開発者への成果物に対する利用許諾のこと。 • 登録したユーザーだけが使用できるようにしたい場合の設定。 • Front APIへのRequestにsubscription keyのセットを必須にする • 開発者は利用許諾の申請を開発者ポータルより行う。(Azureポータルじゃない) サブスクリプション Nextscape Inc. 59 • 申請を自動承認にした場合は、申請 されたら即時 subscription key が発行 される。 • 要承認にした場合は、Portalから管 理者が手動で承認する必要がある。 • 利用許諾の申請が発生してもメール が飛ぶ、Webhookを叩くなどのメン ションを飛ばすことができない(不 便すぎて困る)
  60. 60. • Portalに • 「サブスクリプションの追加」 • 「サブスクライバーの追加」 • の2つの表記があり、用途の違いがわからなくて混乱しちゃうので整理しておく。 サブスクリプション 「サブスクリプションの追加」とは、成果物(製品)と開発者(ユーザー)の両方を指定して承認すること Nextscape Inc. 60
  61. 61. • 成果物(製品)からサブスクリプションを選んだ時には、「サブスクライバーの追加」というメニュー がある。 サブスクリプション 「サブスクライバーの追加」とは、開発者(ユーザー)だけを指定して承認すること Nextscape Inc. 61
  62. 62. • ユーザーが開発者ポータルからサブスクライブする 要承認にした時のサブクライブの挙動 Nextscape Inc. 62
  63. 63. • Subscription name(利用許諾名)は自分で入力する(謎仕様) 要承認にした時のサブクライブの挙動 Nextscape Inc. 63
  64. 64. • リクエストしたので承認待ち状態になる 要承認にした時のサブクライブの挙動 Nextscape Inc. 64
  65. 65. • Azure Portalで見ると、承認待ち状態になっている。 • なぜか「状態」は「送信済み」という表記。(「承認待ち」にしてほしい・・・) • 「サブスクリプションのアクティブ化」をクリックする。 要承認にした時のサブクライブの挙動 Nextscape Inc. 65
  66. 66. • 開発者ポータルを読み込みなおすと、Subscription Keyが発行されている 要承認にした時のサブクライブの挙動 Nextscape Inc. 66
  67. 67. 開発者ポータル Developers Portal ※docsでは「開発者」を「ユーザー」と表記しているページも多いので注意
  68. 68. https://<APIMName>.portal. azure-api.net 開発者ポータルのURLは 管理者権限があるならここ から遷移すればいい Nextscape Inc. 68
  69. 69. 開発者ポータルの見た目(デザイン可能) Nextscape Inc. 69
  70. 70. • 開発者が • 自らユーザーとして登録する機能 • 開発者が使いたい成果物(APIを含んでいる)に対して利用許諾を申請する機能 • APIをお手軽に試すテスト機能 • 不具合を報告する機能(管理者にはmailが飛んでくる) • などを持つ、開発者のための画面。 • APIMagementインスタンスとは全く別のリソースと思ったほうが良い • 開発者ポータルはAPIMagementとは無関係のWebクライアントとして認識したほう がdocsが読みやすい • AzurePortalでは、(基本的に)開発者ポータルへのログインユーザーの権 限管理しかしない • 権限管理以外だと、開発者ポータルがAPIMgmtに対してRequestする前に外部 IDProviderからid_token(JWT)を得る、もしくは認証サーバーからaccess_tokenを得 るための機能のための設定をするぐらい(ややこしいので後述する) そもそも開発者ポータルとは何か Nextscape Inc. 70
  71. 71. 1.Portalから手動で追加する 2.Portalからメールアドレスを入力して招待する 3.開発者ポータルから自分でサインアップ(要セットアップ) 開発者を追加する方法は? 3つの方法がある Nextscape Inc. 71
  72. 72. • Portalからのユーザー追加は ID/PW認証のみ 1.Portalから手動で追加する Nextscape Inc. 72
  73. 73. 2.Portalからメールアドレスを入力して招待する Nextscape Inc. 73
  74. 74. 2.Portalからメールアドレスを入力して招待する Nextscape Inc. 74
  75. 75. 3.開発者ポータルから自分でサインアップ Nextscape Inc. 75
  76. 76. 3.開発者ポータルから自分でサインアップ Nextscape Inc. 76
  77. 77. 3.開発者ポータルから自分でサインアップ Nextscape Inc. 77
  78. 78. 3.開発者ポータルから自分でサインアップ Nextscape Inc. 78
  79. 79. • Portalにログインできて、かつユーザーを管理する権限を付与されているユーザーにしかできない Portalから手動で追加する • 開発者ポータルのID/PWを使ったサインアップ画面へのリンクがメールで飛ぶ • Portalにログインできて、かつユーザーを管理する権限を付与されているユーザーにしかできない • ID/PWサインアップのセットアップが必須(デフォルトでID/PW認証はセットアップされている) Portalからメールアドレスを入力して招待する • 運用者は開発者ポータルのURLを送るだけ良いので一番楽 • ID/PWを使ってサインアップ、もしくは • 外部IDProvider(AzureAD, Facebook, Twitterなど)を使って認証させることができる 開発者ポータルから開発者が自分でサインアップ 開発者を追加する方法は? まとめ Nextscape Inc. 79
  80. 80. セキュリティ->ユーザーで認証方式を登録する Nextscape Inc. 80 開発者ポータルサインアップのセットアップ方法は?
  81. 81. Nextscape Inc. 81 するとサインアップ画面が現れる 開発者ポータルサインアップのセットアップ方法は? これが こうなる でも、これID/PWの場合だけ!
  82. 82. サインアップだとこうなっちゃう サインインなら外部のIDProviderが表示される 外部のIDProvider(FacebookとかTwiterとか)を有効にしたときはサインインを使 わないといけないので注意! 開発者ポータルサインアップのセットアップ方法は? Nextscape Inc. 82 開発者ポータルの カスタマイズが必須 (別に難しくはない)
  83. 83. • 認証の種類にFacebookって出る Facebookで認証してサインアップすると だから何ってわけじゃないけど・・・。 Nextscape Inc. 83
  84. 84. Nextscape Inc. 84 開発者ポータルって日本語化できないの? 完璧じゃないけど一応できる。もうすぐ 無くなってしまう発行者ポータルより設 定可能 (Portalで設定できるようになるはず)
  85. 85. セキュリティ Security
  86. 86. API Managementでいうセキュリティは複数個所ある セキュリティ コンシューマ パブリッシャー API Management 開発者ポータル 1 2 API Client 3 4 Nextscape Inc. 86
  87. 87. Nextscape Inc. 87 用途が混在していてわかりにくいので要注意 Portalのセキュリティセクション 開発者ポータルの認証方式の設定 • クライアント認証の検証時に使う証明書をUploadする • APIを呼び出す時に使う証明書をUploadする (どちらもUploadだけじゃダメで、Policyにて実装が必要) 独自に実装した開発者認証、成果物のサブスクリプションを 行う認証サーバーの設定 • 開発者ポータルの認証方式の設定 • 開発者ポータルからAPIをテストする時にTokenを取得する ために必要な認可サーバー(or IDProvider)の設定 1 2 3 3 4 APIClient 3 「開発者ポータル」で 説明済み 3 2 4は証明書の検証もできるが、PolicyでJWTの検証をするのがメイン1 1 説明済み
  88. 88. • これをセットアップすると、開発者ポータルでTokanを取得できるようになる、というだけ! • 勘違いしがちなのは、これをセットアップするとなんかよくわかんないけど外部の認証サー バー(IDProvider)を使って認証してくれるようになるんだ、なんて思わないこと! • なので、 APIのエンドポイントがむき出しの場合にAPI側で認証結果(JWTとか)を検証する実装 をさぼれる訳じゃない、ということ • API側がFunctionsみたいにアクセスキーがある場合はアクセスキーの検証だけでOKとして、認証結果の検 証を実装しなくてもいいのかは判断が必要 • APIがVNET内部にDeployしてあって外部からの攻撃はない、という場合なら気にしなくていいかも OAuth2.0, OpenIdConnectの使い方 • 開発者ポータルの認証方式の設定 • 開発者ポータルからAPIをテストする時にTokenを取得する ために必要な認可サーバー(or IDProvider)の設定4 3 Nextscape Inc. 88 1 2 3 APIClient 4 説明済み
  89. 89. 開発者ポータルでOAuth2.0のTokenを取得する Nextscape Inc. 89 AzureADという名前を 付けた
  90. 90. • APIにOAuth2.0を使用するようにセットアップ(これが誤解させる元凶) 開発者ポータルでOAuth2.0のTokenを取得する Nextscape Inc. 90
  91. 91. Try it をクリックして 開発者ポータルでOAuth2.0のTokenを取得する Nextscape Inc. 91 承認コードを選択する
  92. 92. • ログインダイアログがポップアップ(ログインしていなかった場合) • アクセス許可の承認を求められる 開発者ポータルでOAuth2.0のTokenを取得する Nextscape Inc. 92 • アクセストークンを取得して保持したこと がわかる
  93. 93. PortalのTest機能は、サブ スクリプションキーを自 動的にHeaderにセットす る機能しかない OAuth2.0, OpenIdConnectの使い方 • PortalのTest機能にはアクセストークンを取得する機能はないので間違えな いように!(開発者ポータルでやること!) Nextscape Inc. 93
  94. 94. • API Managementは認証・認可(承認)の機能は持っていない。あくまでJWTの検証をするPolicy がデフォルトで用意されているだけ • JWTを検証する、ということはIDProviderはAzureAD、B2Cだけしか使えないわけじゃない。 OpenIdConnectをサポートするIDProviderであればなんでも大丈夫 validate-jwt 1 2 3 APIClient 4 は証明書の検証もできるが、PolicyでJWTの検証をするのがメイン1 Client API Mgmt B2C IDProvider JWT JWT • OAuth2.0ではなくOpenId Connectであることに注意。 OAuth2.0の返すaccess_tokenは仕様が策定されてないし、 通常JWTは使用されない。(ランダム文字列) • OpenId Connectであれば、id_tokenがJWTで返却される。 • id_tokenの中にClameが格納されている。 Nextscape Inc. 94
  95. 95. • 最終的に次の構成を組む validate-jwtを試す(敢えてAzureAD以外で) Client API Mgmt JWT API JWT Validate OpenId Connect • その前にまずはローカル環境JWTを取得する実装をして、JWTのValidationもやってみる Client JWTJWT Validate JWT OpenId Connect JWT Client Nextscape Inc. 95
  96. 96. • https://console.developers.google.com • プロジェクトを作る • 既にあるならそれでもいい Google Developers Console Nextscape Inc. 96
  97. 97. Google+ APIを追加する Nextscape Inc. 97
  98. 98. • 認証にはこのAPIの追加が必要、というBlogもあれば、不要、というBlogもある • 今回はそこがポイントじゃないので取り合ず追加しとく • (多分追加は不要だと思われる。オワコンだし) Google+ APIを追加する Nextscape Inc. 98
  99. 99. 認証情報を作る Nextscape Inc. 99
  100. 100. 認証情報を作る Nextscape Inc. 100
  101. 101. • アプリケーション名を入 れる • 他の項目はそのままでい い 認証情報を作る Nextscape Inc. 101
  102. 102. 認証情報を作る 認証後にGoogleAPIからid_tokenが 戻ってくるリダイレクト先のURI。 まだWeb画面作っていないので後で 入力する Nextscape Inc. 102
  103. 103. • メモらなくてもいつでも 確認できる 認証情報を作る Nextscape Inc. 103
  104. 104. • ASP.NET Core 2.1で作る • VS, VSCodeのどっちでもいいけど個人認証ありでプロ ジェクトを作る • dotnet new mvc --auth Individual (VSCodeの場合) Webクライアントを作る JWTJWT ValidateOpenId Connect JWT Nextscape Inc. 104
  105. 105. • GoogleのOpenId Connectによる認証を実施する設定 • StartUpクラスのConfigureServicesメソッドに次の実装をする Webクライアントを作る services.AddAuthentication() .AddGoogle(googleOptions => { googleOptions.ClientId = Configuration["Authentication:Google:ClientId"]; googleOptions.ClientSecret = Configuration["Authentication:Google:ClientSecret"]; googleOptions.Scope.Add("https://www.googleapis.com/auth/plus.login"); googleOptions.SaveTokens = true; }); • SaveTokens = trueにセットしておくと、id_tokenがHttpContextにセットされて ほしいんだけどされない。(access token, refresh token専用らしい) • Contollerで • とすればid_tokenが取得できて、これをHeaderに入れてWebAPIに投げたかった • でもどうやってもid_tokenをControllerに渡せなかった・・・。 HttpContext.GetTokenAsync("id_token") ClientId、ClientSecretは Google Dev Consoleで認証 作成した結果をセットする 「ユーザーシートク レット]ってやつ dotnet user-secrets –h でヘルプが出る Nextscape Inc. 105
  106. 106. launchSettings.jsonは、 Propertiesフォルダ内にある SSL Portを確認してRedirectURlをGoogleに登録 Nextscape Inc. 107
  107. 107. • ミドルウェアを使った場合、RedirectURIのリソース名はsignin-googleで固定。今回は https://localhost:44315/signin-google となる • FacebookやAzureADの場合は、signin-xxxのxxxが変わる • このRedirectURIが一致しないとエラーになるので間違えないように • 認証情報 -> 作った認証情報右にある鉛筆アイコンをクリックする SSL Portを確認してRedirectURlをGoogleに登録 Nextscape Inc. 108
  108. 108. • RedirectURIは複数登録で きるので便利 (本番、テスト用にそれ ぞれ作る必要がない) SSL Portを確認してRedirectURlをGoogleに登録 Nextscape Inc. 109
  109. 109. 画面を動かして確認 Nextscape Inc. 110
  110. 110. または 画面を動かして確認 Nextscape Inc. 111
  111. 111. 画面を動かして確認 Nextscape Inc. 112
  112. 112. ログイン成功 Nextscape Inc. 113 ログイン時のメルア ドが表示される
  113. 113. • 本当はControllerからWebAPIを呼ぶ実装にしたかったが、取得したid_token をControllerに渡せないため、手動でid_tokenを取得しておいてPOSTMANを 使ってWebAPIを叩くことにする。 id_tokenの取得 ブレイクポイントを 置いて、この id_token変数の中身 を見る Nextscape Inc. 115
  114. 114. WebAPIを作る JWTJWT ValidateOpenId Connect JWT • ASP.NET Core 2.1で作る • VS, VSCodeのどっちでもいいけど個人認証ありでプロ ジェクトを作る • dotnet new webapi (VSCodeの場合) Nextscape Inc. 116
  115. 115. • services.AddMvcメソッドの上に実装する JWTのValidation実装をStartupクラスにする Nextscape Inc. 117 services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.SaveToken = true; options.Audience = Configuration["Authentication:Google:ClientId"]; options.Authority = "https://accounts.google.com"; options.TokenValidationParameters = new TokenValidationParameters { ValidateIssuer = true, ValidateAudience = true, ValidateLifetime = true, ValidateIssuerSigningKey = true, NameClaimType = "name", AuthenticationType = "Google." + JwtBearerDefaults.AuthenticationScheme, ValidIssuers = new[] { options.Authority, "accounts.google.com" }, }; }); ClientIdはGoogle Dev Consoleで認証作成した結 果をセットする
  116. 116. • StartupクラスのConfigureメソッドに次の一行を実装 認証ミドルウェアを有効化 if (env.IsDevelopment()) { app.UseDeveloperExceptionPage(); } else { app.UseHsts(); } app.UseAuthentication(); app.UseHttpsRedirection(); app.UseMvc(); Nextscape Inc. 118
  117. 117. APIに簡単な実装をしておく [Authorize] [Route("api/[controller]")] [ApiController] public class ValuesController : ControllerBase { // GET api/values [HttpGet] public ActionResult<IEnumerable<string>> Get() { return new string[] { User.Identity.Name, User.Claims.Count().ToString() }; //return new string[] { "value1", "value2" }; } Nextscape Inc. 119
  118. 118. • httpsの検証をOffにしておく POSTMANでAPIを叩いてみる Nextscape Inc. 120
  119. 119. 最初は401になるのが正解 Nextscape Inc. 121
  120. 120. • ちゃんと結果 がとれた JWTをAuthヘッダーに入れて呼び出す Nextscape Inc. 122
  121. 121. 間にAPI Managementを挟む API Mgmt JWT Validate Client JWT JWT Validate OpenId Connect JWT API 手動JWT セット Client JWT JWT Validate OpenId Connect JWT API 手動JWT セット Nextscape Inc. 123
  122. 122. • 動作確認OK WebAPIをAzure WebAppsにデプロイした Nextscape Inc. 124
  123. 123. • サブスクリプションは不要にしてある WebAppsをAPIMのAPIに登録して成果物と紐づけ Nextscape Inc. 125
  124. 124. validate-jwtを実装する(APIレベルに対して) Nextscape Inc. 126
  125. 125. • ClientIdを入れるだけで実装終了 validate-jwtを実装する(APIレベルに対して) <inbound> <base /> <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed- validation-error-message="Unauthorized" require-expiration-time="true" require- scheme="Bearer" require-signed-tokens="true" clock-skew="0"> <openid-config url="https://accounts.google.com/.well-known/openid-configuration" /> <audiences> <audience><!-- ClientId --></audience> </audiences> <issuers> <issuer>accounts.google.com</issuer> <issuer>https://accounts.google.com</issuer> </issuers> </validate-jwt> </inbound> Nextscape Inc. 127
  126. 126. • JWTなしの場合 確認 Nextscape Inc. 128
  127. 127. Nextscape Inc. 129
  128. 128. • curl https://accounts.google.com/.well-known/openid-configuration (おまけ)GoogleのエンドポイントはDiscovery Docから取得 Nextscape Inc. 130
  129. 129. • https://www.googleapis.com/oauth2/v3/certs • 1時間に1回変わるそうなので、自前でValidateするとキツそう (おまけ)Googleと検証側で共有する公開鍵 Nextscape Inc. 131
  130. 130. • Clientが渡してきたクライアント証明書を検証する実装 証明書の使い方 • クライアント認証の検証時に使う証明書をUploadする • APIを呼び出す時に使う証明書をUploadする (どちらもUploadだけじゃダメで、Policyにて実装が必要)2 1 <choose> <when condition="@(context.Request.Certificate == null || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" > <return-response> <set-status code="403" reason="Invalid client certificate" /> </return-response> </when> </choose> ※未検証 Nextscape Inc. 132 1 2 3 APIClient 4
  131. 131. • APIを呼び出す時にクライアント証明書を渡す実装方法 証明書の使い方 • クライアント認証の検証時に使う証明書をUploadする • APIを呼び出す時に使う証明書をUploadする (どちらもUploadだけじゃダメで、Policyにて実装が必要)2 1 <inbound> <authentication-certificate thumbprint="thumbprint" /> <base /> </inbound> ※未検証 Nextscape Inc. 133 1 2 3 APIClient 4
  132. 132. 構成パターン Construction pattern
  133. 133. • 公開エンドポイントのセキュリティに注意。 • APIMgmtのPublicIPは、自分からインスタンスを消さない限り固定なので、ホワイトリスト対応が可能なPaaSならそれ でOKとして良いかも 公開されたエンドポイントのProxyにする構成 コンシューマ Client Azure On-Premiss APIMgmt 開発者ポータル DMZ VNET Public IP WebApps Functions 開発者 公開されたエンドポイント Nextscape Inc. 135
  134. 134. • APIMgmtからVNET内部のリソースにアクセス可能です。 • ServiceEndpointに接続したリソースは403エラーになるのでNG(確認した) VNETのリソースを外部公開する構成 コンシューマ Client APIServer VNET SubnetSubnet APIMgmt APIMgmtが接続する専用のサブネット が必要。このサブネットには他のリ ソースが割り当てられていてはNG 最小/29 開発者 Azure On-Premiss 開発者ポータル VPN Gateway Nextscape Inc. 136
  135. 135. • オンプレからのAPIアクセスも外を通らない • DNSに注意がいる(DNS立てないと名前解決全滅。Portalのテストすら動かない!) 内部だけに公開する構成 コンシューマ Client APIServer VNET SubnetSubnet APIMgmt 開発者ポータル 最小/29 Azure On-Premiss 開発者 VPN Gateway 開発者ポータルは、外部からも内部からもアクセスで きなくなる。VNET内部にデプロイされるわけではな いので、内部IPが割り当てられない。 Nextscape Inc. 137
  136. 136. • Portalのテストすら動かない APIMgmtをVNET内部に置いた場合 名前解決に失敗している Nextscape Inc. 138
  137. 137. DevまたはPremiumレベル(月額319,064! )でないと「仮想ネットワーク」は表示されない (表示されない=VNETに接続できない) VNETにつなげるにはPremiumレベル必須 Nextscape Inc. 139
  138. 138. バージョン管理 Version Management
  139. 139. • API Managementではリビジョンとバージョンの2つの機能でAPIのメンテ ナンスすることができる リビジョンとバージョン Nextscape Inc. 141 リビジョン • WebAppsのスロット機能ととても良 く似た仕組み。API単位に作成可能。 バージョン • 異なるバージョンのAPIを同時に公 開するためのもの。 • リビジョンごとに別API別URLになる • 複数のリビジョンを作成できる • リビジョンを指定して本番APIに切り替え
  140. 140. リビジョン Nextscape Inc. 142 • Revisionを作成すると、Revsion番号が新しく発番されて、;rev=<num>という文字列が 入った新しいURLが作成される WebAppsのスロット同じ目的の機能と理解すればいい URLの例 https://<resourceName>.azure- api.net/echo;rev=2/resource • 特定のRevisionをメインに切り替えると、;rev=<num>の付与も切り替わる メインURL(Revision=1) https://<resourceName>.azure-api.net/echo/resource Revision=2のURL https://<resourceName>.azure- api.net/echo;rev=2/resource Revision=1のURL https://<resourceName>.azure- api.net/echo;rev=1/resource メインのURL https://<resourceName>.azure-api.net/echo/resource Revision=2をメインに切り替え
  141. 141. リビジョン Nextscape Inc. 143 • Revsionが入ったURLは、知っていれば誰でもアクセスできてしまうので、サブスクリプション キー必須にするなどしてAPIを守るようにすること リビジョン使用時の注意 • 本番で稼働しているAPI定義やPoliciyに影響を与えることなく、安全に変更することができる • APIM定義をPublishする前に稼働確認ができる • 切り替え時に変更点を記載すると開発者ポータルに表示できるため、開発者に対して何をし たのかアナウンスできる • リビジョンの切り替えがすぐ反映されるので、問題があったらすぐにロールバックできる (即時反映なので、DNS切り替えではないみたい) リビジョンを使用する理由
  142. 142. リビジョンの作成方法 Nextscape Inc. 144
  143. 143. • リビジョン一覧画面に表示される説明文。後から修正できる リビジョンの作成方法 Nextscape Inc. 145
  144. 144. • RevisionのIDは自動採番される リビジョンの作成方法 URLの例 https://<resourceName>.azure-api.net/echo;rev=2/resource?param1=sample Nextscape Inc. 146
  145. 145. このリビジョンをメインとして公開する リビジョンの管理 Nextscape Inc. 147 このリビジョンを削除する このリビジョンを非公開にする
  146. 146. Nextscape Inc. 148 • 特定のリビジョンを公開しようとするとこんなダイアログがあがる APIの更新ログ
  147. 147. Nextscape Inc. 149 • 書いた内容が開発者ポータルに公開される APIの更新ログ
  148. 148. • 例 /v1, /ver1 パス • 例 ?ver=1, ?api-ver=2, ?api-version=2018-11-01 クエリ文字列 • 例 ver:v1, api-ver:2, api-ver:2018-11-01 Header バージョン Nextscape Inc. 150 同時に複数のバージョンのAPIを公開する機能 バージョン文字列は、好き な文字列が使用可能(数字、 日付、名前など) バージョンの差異はバージョン文字列を次の3種類のいずれかに埋め込む
  149. 149. • APIの各バージョンは開発者ポータルで一覧で表示される バージョン Nextscape Inc. 151
  150. 150. • API公開後にバージョニングを開始すると、最初のバージョンのURLを変更できない(ユーザーに影 響がある)ため、混乱を招いてしまう。 バージョン使用時の注意点 バージョン Nextscape Inc. 152 最初のバージョンのURL https://<resourceName>.azure-api.net/<api>/<operation> バージョニングしたURL htps://<resourceName>.azure-api.net/<api>/v2/<operation> • 破壊的な更新をリリースすることができる バージョンを使用する理由 この2つのURLが同 時に使用可能な状態
  151. 151. Nextscape Inc. 153 この例ではblank APIだが、 1. Fullを選択 2. Version this API?に チェック でバージョニング開始と なるのは他のテンプレー トを選んでも同じ API作成時にバージョニングを開始する
  152. 152. API作成後でバージョニングを開始する Nextscape Inc. 154
  153. 153. API作成後でバージョニングを開始する Nextscape Inc. 155
  154. 154. Nextscape Inc. 156 バージョニング開始前API。 何もしなければURLは元のままだが、この APIにバージョンを後から追加もできる ※URLが変わるということ。 ※適用は慎重に!(ユーザーに影響)
  155. 155. だったらバージョニングは、最初からするべき 公開前であれば、影響なく後からバージョニングを開始できるので慌てて作り直さないこと どうやって使い分けするのか バージョンとリビジョンは目的が異なるため、どちらかだけ使用するのでもいいが、どう考えても 両方使用することになる バージョンとリビジョンの使い方 Nextscape Inc. 157 1. 次のバージョンを作る 2. 最初のAPIをバージョンを指定 3. 次のバージョンを消す
  156. 156. Nextscape Inc. 158 docs では透過的バージョンアップという手法が提案されている • https://docs.microsoft.com/ja-jp/azure/api-management/api-management-sample-cache- by-key#transparent-versioning • APIM側のバージョンアップにクライアントが合わせるのではなく、クライアント に合わせてAPIM側がバージョンを切り替えるやり方のことらしい クライアントに影響を与えないバージョンアップ戦略 API APIM 通常はクライアントが バージョンを選択する API APIM 透過的バージョンアップは APIMがバージョンを選択する BackendAPI v1 v2 v3 v1 v2 v3 BackendAPI v1 v2 v3
  157. 157. Nextscape Inc. 159 docsに記載されているサンプルの図解 • どのクライアントがアクセスしてきたのかをSubscriptionKeyで判定する方法 透過的バージョンアップの構成 API APIM BackendAPI v1 v2 v3 1.HeaderにSubscriptionKey を入れてRequest バージョン管理 2. SubscriptionKeyをキーにキャッシュに データがあるかを確認 3. データがキャッシュがな かったら、SubscriptionKeyを キーに外部からバージョンを 取得し、キャッシュへ格納 4.BackendAPIのURLを取得し たバージョンに書き換え キャッシュにはSubscriptionKeyを キーにバージョンが格納されている KeyValueのキャッシュ機能が APIMにはある(フラグメント キャッシュ)
  158. 158. Nextscape Inc. 160 docs の日本語が難しいが、恐らくこういうことが言いたいんだと思われる • https://docs.microsoft.com/ja-jp/azure/api-management/api-management-sample-cache- by-key#tenant-isolation バックエンドの障害対応と段階的ロールアウト API APIM BackendAPI v1 BackendAPI v1 BackendAPI v1 v1 同じバージョンのBackendAPIを複数用意 しておき、クライアントがどの BackendAPIにアクセスするのかをAPIMが 判定するように設計する • 設定方法は透過的バージョンアップとほ ぼ同じ • BackendAPIのハードウェア障害が起こった時 に、影響があるクライアントが限定される • BackendAPIのハードウェアごとにバージョン アップをしていくことで段階的にロールアウ トが可能となる(似非カナリアリリース)
  159. 159. API Management のエラー処理 Error handling
  160. 160. API Management のエラー処理 Nextscape Inc. 162 • API Mamagementでいうエラーは、Policyで発生したエラーと、Backend API で発生したエラーと二種類あることを意識しておくこと Policy In Out Err API (Backend) (Publisher) Client (FrontEnd) (Consumer) Backend BackendAPIのResponseが 4xx, 5xxの場合 <outbound>でエラーハン ドリング PolicyがエラーをThrowの場合 <on-error>でハンドリング API Management
  161. 161. • <inbound>,<backend>,<outbound>セクションのいずれかに設定したポリシーで発生したエラー は即時<on-error>セクションへ飛ぶ • Policyが発生させるエラーの種類は、事前定義されたものだけ。設定と異なる状況になったら エラーがThrowされる • docsには と書いてあるが、実際には4xx、5xxコードが返却されるようだ エラーハンドリングは <on-error>セクション に実装する Policyで発生したエラーへの対処 Nextscape Inc. 163 ※Policy内部ではエラーをThrowできない。(Exceptionクラスが使えないから) もし、<return-response>ポリシーでエラーのResponseを返却するように実装した場合、 Responseは<on-error>, <outbound>セクションを通らないので注意
  162. 162. • エラー処理の例 Policyで発生したエラーへの対処 Nextscape Inc. 164 <policies> <inbound> <rate-limit calls="5" renewal-period="60" /> <quota calls="100" renewal-period="604800" /> <base /> </inbound> ・・・ <on-error> <base /> </on-error> </policies> エラー処理はまだ入れていない 1分間に5回までのリクエスト制限 わざと1分以内に6回リクエストした Policyが返却した 独自のStatusCode
  163. 163. • エラー処理を実装した Policyで発生したエラーへの対処 Nextscape Inc. 165 <on-error> <base /> <choose> <when condition="@(context.Response.StatusCode == 429)"> <return-response> <set-status code="499" reason="catch error in onerror" /> <set-header name="ErrorSource" exists-action="override"> <value>@(context.LastError.Source)</value> </set-header> <set-header name="ErrorReason" exists-action="override"> <value>@(context.LastError.Reason)</value> </set-header> ・・・ <set-body>Response is customized in on-error.</set-body> </return-response> </when> <otherwise /> </choose> </on-error> ResponseのStatusCodeが429の場合は499を返却する わざと1分以内に6回リクエストした ※API Managementでは、Custom の Http StatusCodeは101~599の範囲のみ設定可能 エラー詳細をHeaderへセット(全実装は次ページ) なぜかReason を表示してく れない・・・
  164. 164. • エラーの詳細情報をheaderへセットする実装(docsまんまだけど) Policyで発生したエラーへの対処 <on-error> <set-header name="ErrorSource" exists-action="override"> <value>@(context.LastError.Source)</value> </set-header> <set-header name="ErrorReason" exists-action="override"> <value>@(context.LastError.Reason)</value> </set-header> <set-header name="ErrorMessage" exists-action="override"> <value>@(context.LastError.Message)</value> </set-header> <set-header name="ErrorSection" exists-action="override"> <value>@(context.LastError.Section)</value> </set-header> <set-header name="ErrorStatusCode" exists-action="override"> <value>@(context.Response.StatusCode.ToString())</value> </set-header> <base /> </on-error> Nextscape Inc. 166 • デバッグ用途の実装ならこ れでいい • 本番用の実装では逆に詳細 を出力しすぎないようにし ないといけない • Sectionの情報は出力し ない、とか • 本番用の実装では、エラー 発生時にだけロギングする 仕掛けが必要。<on-error> でEventHubへの出力を検討 すること • Storageへの出力だと確 実に出力される保証が ない
  165. 165. • context.Response.StatusCodeを使って、対処方法を分岐させる • 基本的なエラー処理の方針は、Responseの加工となる(必要なら加工する) • エラーの発生時のログ出力は通常はAPI側で実装していなければいけないが、APIMでログ出力 をする必要があるならここでEventHubへ出力する実装をする エラーハンドリングは <outbound>セクション に実装する Backend APIで発生したエラーへの対処 Nextscape Inc. 167 <outbound> <base /> <choose> <when condition="@(context.Response.StatusCode>=500)"> <return-response> <set-status code="499" reason="ChangeStatusCode" /> <set-body>Error Raised in backend API.</set-body> </return-response> </when> <otherwise /> </choose> </outbound> ResponseのStatusCodeが5xx系の場 合は499を返却する
  166. 166. ロギング logging
  167. 167. APIMで取得できるログの種類 ロギング • Azureのリソースが出力する 自身のデータ。リソースの種 類によって出力されるデータ が異なる。APIMの場合、 TotalRequests数や FailedRequests数など。 • メトリックの数値を元にア ラートを設定することが多い。 メトリックス Nextscape Inc. 169
  168. 168. • Azureのリソースを 外部から操作した 操作ログ。APIMの 場合、”Create API” や”Add API to Product”など。 アクティビティ ロギング APIMで取得できるログの種類 Nextscape Inc. 170
  169. 169. • 監査・トラブルシューティングに 使用するためにAzureリソースが出 力するログ。 • API Management は、個々の API 要 求についての診断ログ を数分に1回 出力する。リアルタイム性はない • 事前定義されたスキーマしか出力 できない 診断ログ ロギング APIMで取得できるログの種類 Nextscape Inc. 171
  170. 170. • EventHubsへ出力する設定をやってみた ロギング Nextscape Inc. 172 これはEventHubsのポリシー。ポリシー 毎にアクセス権が設定されている。 これにCheckを入れないとEventHubsへ 診断ログが出力されない 1Requestごとの診断ログ。 5分に1回、1分毎5分間のログを出力 (※ Requestがあった場合だけ)
  171. 171. • 診断ログのEventHubs への出力 • GatewayLog(1Request についてのログ)は約 1分ごとに出力される が、観察していると消 失するログもある • GatewayRequests, Capacity(メトリッ ク)はRequestがあった 時は1分間隔のログを5 分間分、5分に1回出力 する • Docsには「1時間に1回 出力する」と記載があ るが違うみたい ロギング 診断ログをEventHubsへ出力する設定 をして、StreamAnalitycs->Functionsへ と接続した Nextscape Inc. 173 1分ずつ、5分間のログ
  172. 172. • GatewayLogにて出力され るエラーログはこんな感 じ ロギング Nextscape Inc. 174 { "Level": 4, "isRequestSuccess": 0, "time": "2018-11-05T13:57:09.0583391Z", "operationName": "Microsoft.ApiManagement/GatewayLogs", "category": "GatewayLogs", "durationMs": 0, "callerIpAddress": "13.91.254.72", "correlationId": “********-****-****-****-************", "location": "Japan West", "properties": { "lastError": { "source": "validate-jwt", "reason": "TokenNotPresent", "message": "JWT not present.", "scope": "api", "section": "inbound" }, "method": "GET", "url": "https://nsuesaka.azure-api.net/echo/resource?param1=sample", "responseCode": 401, "responseSize": 118, "cache": "none", "apiId": "echo-api", "operationId": "retrieve-resource", "productId": "starter", "clientProtocol": "HTTP/1.1", "apiRevision": "1" }, “resourceId”: “/SUBSCRIPTIONS/*******-****-****-…" } エラーを出力したポリシー ポリシーのスコープ ポリシーを実装したセクション • この情報以上は出力できな いので、例えばこのリクエ ストは誰?という特定はで きない
  173. 173. • フルカスタマイズしたログを出力したいならこのポリシーを使う • docsにはREST APIを使用する例しかないが、PowerShellのほうが全然簡単 EventHubへ出力するポリシー Nextscape Inc. 175 $context = New-AzureRmApiManagementContext ` -ResourceGroupName <resourceGroupName> ` -ServiceName <serviceName> New-AzureRmApiManagementLogger ` -Context $apimContext ` -LoggerId "LoggerId123" ` -Name “eventHubName" ` -ConnectionString ` "Endpoint=sb://<eventHubNameSpace>.servicebus.windows.net/;SharedAccessKeyName=SendKey;SharedAc cessKey=<key>" ` -Description “Test logger" 設定先のAPI Management のContextオブジェクトを取得する 任意の文字列 任意の文字列 EventHub名 API ManagementにEventHub対応のロガーを作成
  174. 174. API Managementに設定したロガーの一覧 EventHubへ出力するポリシー Nextscape Inc. 176 Get-AzureRmApiManagementLogger ` -Context $apimContext • おまけのコマンド一覧 API Managementに設定したロガーの削除 Remove-AzureRmApiManagementLogger ` -Context $apimContext ` -LoggerId <loggerId>
  175. 175. Nextscape Inc. 177 • <log-to-eventhub>ポリシーの書き方 • <log-to-eventhub>は<inbound>, <backend>, <outbound>, <on-error>で記載可 EventHubへ出力するポリシー <inbound> <base /> <log-to-eventhub logger-id=“<LoggerId>”>@(“文字列ならOK!”)</log-to-eventhub> </inbound> <inbound> <base /> <log-to-eventhub logger-id="LoggerCreatedFromPowerShell">@( string.Join(",", DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress, context.Operation.Name) )</log-to-eventhub> </inbound> • 実装例 • contextから色々引っ張ってくるべし
  176. 176. Nextscape Inc. 178 • うまく実装できると、Traceにこんな感じで出力される EventHubへ出力するポリシー log-to-eventhub (0.163 ms) { "message": "Expression was successfully evaluated.", "expression": " string.Join(¥",¥", DateTime.UtcNow, context.Deployment.ServiceName, context.RequestId, context.Request.IpAddress, context.Operation.Name) ", "value": "11/20/2018 12:13:58 PM,nsuesaka.azure-api.net,545118f2-18db-4044-8ac2- 4d0102fdfcd2,13.91.254.72,Retrieve resource“ } log-to-eventhub (0.055 ms) { "message": "Log to EventHub Policy was successfully processed“ }
  177. 177. Nextscape Inc. 179 • EventHubからデータを取得してみるとこんな感じ EventHubへ出力するポリシー
  178. 178. Nextscape Inc. 180 • ゴリゴリに加工したログ(docsより) EventHubへ出力するポリシー <log-to-eventhub logger-id="conferencelogger" partition-id="0"> @{ var requestLine = string.Format("{0} {1} HTTP/1.1¥r¥n", context.Request.Method, context.Request.Url.Path + context.Request.Url.QueryString); var body = context.Request.Body?.As<string>(true); if (body != null && body.Length > 1024) { body = body.Substring(0, 1024); } var headers = context.Request.Headers .Where(h => h.Key != "Authorization" && h.Key != "Ocp-Apim-Subscription-Key") .Select(h => string.Format("{0}: {1}", h.Key, String.Join(", ", h.Value))) .ToArray<string>(); var headerString = (headers.Any()) ? string.Join("¥r¥n", headers) + "¥r¥n" : string.Empty; return "request:" + "¥n" + requestLine + headerString + "¥r¥n" + body; } </log-to-eventhub>
  179. 179. Log Analyticsへ接続する Nextscape Inc. 181
  180. 180. Nextscape Inc. 182 • Log Analyticsへの結果出力は1時間に1回 ぐらい?すごく遅いので、名前の通り あくまで分析用 Log Analyticsへ接続する 通信量
  181. 181. スケーリング Scaling
  182. 182. ユニット、という単位でスケールする スケーリング Nextscape Inc. 184 レベル Developer Basic Standard Premium 最大ユニット数 1 2 4 10/リージョン 料金 5483.28/月 16,799.52/月 78,387.84/月 319,064.4/月 7.37/時間 22.58/時間 105.36/時間 428.85/時間 SLA 99.9% 99.9% 99.9% 99.95% 予測最大スループット/ユニットごと 500 Req/Sec 1000 Req/Sec 2500 Req/Sec 4000 Req/Sec (2018/11 東日本の単価。課金は時間単位) • 1ユニットの作成には15分~40分かかる ※ユニット=APIMインスタンス、の理解で間違いない
  183. 183. 複数リージョンへのデプロイが可能 • Premiumレベルの場合のみ設定可能。2リージョン以上へのデプロイでSLAが99.95%になる 自動スケール • Standard、Premiumレベルの場合のみ設定可能 • ユニットの増加は20分以上かかる • 複数リージョンへデプロイしている場合、自動スケールはプライマリリージョンだけが対象 • プライマリリージョン:最初にAPIMを作ったリージョンのこと スケーリング Nextscape Inc. 185
  184. 184. Nextscape Inc. 186 • スケールしてみる スケーリング
  185. 185. Nextscape Inc. 187 • 複数リージョンへデプロイしてみる 複数リージョンへのデプロイ
  186. 186. Nextscape Inc. 188 複数リージョンへのデプロイ
  187. 187. Nextscape Inc. 189 パフォーマンスへの影響 • BackendAPIは元のリージョンに1つだけだと、プライマリリージョン以外にデプロイされたAPIMはアクセ スがある度に異なるリージョンのBackendAPIを叩きに行くため、パフォーマンスが悪い 解決方法は2つ • BackendAPIも各リージョンへデプロイし、APIMがデプロイされている場所に応じてBackendAPIを切り替え るようにポリシーを作成する • キャッシュを使う(キャッシュのセクションを参照) 複数リージョンへのデプロイの懸念点
  188. 188. Nextscape Inc. 190 • APIM自身がどのリージョンにデプロイされているかを判定して、 BackendAPIを切り替えるポリシーの例 複数リージョンへのデプロイ <inbound> <base /> <choose> <when condition="@("West US".Equals(context.Deployment.Region, StringComparison.OrdinalIgnoreCase))"> <set-backend-service base-url="http://contoso-us.com/" /> </when> <when condition="@("East Asia".Equals(context.Deployment.Region, StringComparison.OrdinalIgnoreCase))"> <set-backend-service base-url="http://contoso-asia.com/" /> </when> <otherwise> <set-backend-service base-url="http://contoso-other.com/" /> </otherwise> </choose> </inbound> docに記載されているもの
  189. 189. Nextscape Inc. 191 • なぜかAPIMの自動スケールはAzure Monitorから設定する 自動スケール
  190. 190. Nextscape Inc. 192 自動スケール
  191. 191. Nextscape Inc. 193 自動スケールの設定は、メトリックを基にするか、スケジュールするかの2択。 だがインスタンス数の増減に20分以上もかかるので、メトリックを基にするのは 現実的じゃない。スケジュールによる設定しか使わないだろう。 自動スケール • スケジュールによる自動スケール設定は、条件(condition)を3つ作成する。1つ目はデフォルト設定。
  192. 192. Nextscape Inc. 194 • 2つ目の条件 スケールアウトの設定例 自動スケール • 3つ目の条件 スケールインの設定例
  193. 193. キャッシュ Cache
  194. 194. キャッシュは2つのポリシーを対で設定する • キャッシュからデータを取得するポリシー cache-lookup を inboundに設定 • データをキャッシュに格納するポリシー cache-store を outboundに設定 キャッシュ Nextscape Inc. 196 <inbound> <base /> <cache-lookup vary-by-developer="false" vary-by-developer-groups="false> <vary-by-header>Accept</vary-by-header> <vary-by-query-parameter>version</vary-by-query-parameter> </cache-lookup> </inbound> <outbound> <cache-store duration="seconds" /> <base /> </outbound> 開発者キーごとに応答 をキャッシュするか 開発者グループごとに応 答をキャッシュするか キャッシュするポリシーを設定 キャッシュを検索す るポリシー キャッシュ保持時間を設定 キャッシュする単位。 複数指定可能
  195. 195. • キャッシュする場所と数 CDNとの違い Nextscape Inc. 197 • 事前キャッシュ CDN Edgeサーバーが全世界各地に配置してある。Edgeまでの物理的な距離が近いほどEdgeまで の到達時間は早いためキャッシュしてあればレスポンスは速い。が、キャッシュする場所 が多いということはOriginアクセスも意外と多い API Management テナント単位の共有データ キャッシュ。(テナント=作成済みAPIMリソース)が使用され るため、1リージョン1キャッシュ。複数のユニットにスケールアップしても、同じ キャッシュ データにアクセス可能。ただし、複数リージョンにデプロイした場合はそれぞ れのリージョン別のキャッシュとなる CDN できる。Poralから、もしくはAPIを使用したキャッシュも可能 API Management できない。<outbound>ポリシーでキャッシュするので、事前にはできない
  196. 196. • パージ CDNとの違い Nextscape Inc. 198 • キャッシュコントロール CDN 任意のタイミングでキャッシュを削除できる。Poralから、もしくはAPIを使用した削除も 可能 API Management 任意に削除できない。キャッシュ保持経過時間が過ぎるのを待つしかない CDN • クエリ文字列ごとに違うキャッシュにできる • Http-Headerの各種メタごとに違うキャッシュにできる API Management CDNと同じ
  197. 197. 明示的にKeyを指定して値をキャッシュする機能のこと docsには例として、他のサービスから取得したユーザープロファイルをユーザーIDをKeyにして キャッシュし、それをResponseに埋め込む、というやり方を解説している(次頁で図解) フラグメントキャッシュとは Nextscape Inc. 199 https://docs.microsoft.com/ja-jp/azure/api-management/api-management-sample-cache-by-key#fragment-caching 色々できる柔軟性は素晴らしいが、そこまでAPI Managementで実装するのはやり過ぎではないだろうか・・・
  198. 198. • docs記載のシナリオを図解 Nextscape Inc. 200 フラグメントキャッシュとは 1. Request API 2. キー使ってキャッシュに 顧客データがあるかを確認 顧客データ 航空予約システム 4.予約データを取得 3. キャッシュに顧客データが なかったら、外部からデータ を取得し、キャッシュへ格納 6. Response 5.取得した予約デー タの一部のプレース ホルダに対して、顧 客データをセット顧客データを埋めるプ レースホルダが予約デー タにある、という前提が 現実的じゃない
  199. 199. フラグメントキャッシュとは Nextscape Inc. 201 • フラグメントキャッシュポリシーは3つのポリシーを使う キャッシュから値を取得するポリシーcache-lookup-value • このポリシーで取得した値は、context.variables[keyName]に格納される 値をキャッシュに格納するポリシーcache-store-value • key, value, durationを設定する 必要に応じてフラグメントキャッシュを削除する • cache-remove-value ポリシー 詳しくはこちら https://docs.microsoft.com/ja-jp/azure/api-management/api-management-caching-policies
  200. 200. • 実装例(docsより) Nextscape Inc. 202 フラグメントキャッシュとは <inbound> <cache-lookup-value key="@("userprofile-" + context.Variables["enduserid"])“ variable-name="userprofile" /> <choose> <when condition="@(!context.Variables.ContainsKey("userprofile"))"> <send-request mode="new“ response-variable-name="userprofileresponse“ timeout=“10“ ignore-error="true"> ・・・ </send-request> <set-variable name="userprofile“ value="@(((IResponse)context.Variables["userprofileresponse"]).Body.As<string>())" /> <cache-store-value key="@("userprofile-" + context.Variables["enduserid"])“ value="@((string)context.Variables["userprofile"])“ duration="100000" /> </inbound> “userprofile-xxxx”というキーで キャッシュから値を取得 値がなかったら データをキャッシュへ格納 外部からデータを取得して 変数に格納
  201. 201. Backup / Restore Backup / Restore
  202. 202. Backup / Restoreコマンド API の Export / Import Git の Repository を Clone 3種類の Backup / Restoreがある Nextscape Inc. 204
  203. 203. Backup / Restore コマンド 誰もがイメージする Backup/Restoreはこの機能のこと REST APIもしくはPowerShellコマンドしか用意されていない(Portal に該当機能なし) バックアップした結果はBlob Storageへ格納される(Blobのリージョンとレベルに注意。 APIMと同じリージョンにLRSで保存するとDR的には意味がないってこと) Backup時と同じレベル(Dev, Basic, Std, Prem)のインスタンスしかRestoreできない 30日以内のバックアップしか復元できない!(エラーになってしまう) バックアップを元に新しいAPI Managementインスタンスを作成可能 Nextscape Inc. 205 REST APIを使うためにはAzrueADに 設定が必要。かなり面倒なのでお 勧めしない(PowerShellがいい)
  204. 204. Backup / Restore コマンド Nextscape Inc. 206 PS C:¥> # バックアップ先のStorageのContextを取得する PS C:¥> $storageContext = New-AzureStorageContext -StorageAccountName "ContosoStorage" -StorageAccountKey $storageKey PS C:¥> PS C:¥> # バックアップ実行 PS C:¥> Backup-AzureRmApiManagement ` >> -ResourceGroupName "ContosoGroup02" ` >> -Name "ContosoApi" ` >> -StorageContext $storageContext ` >> -TargetContainerName "ContosoBackups" ` >> -TargetBlobName "ContosoBackup.apimbackup" PowerShell によるバックアップ(REST APIに比べて圧倒的に簡単!) • バックアップしてみる たった2つのコマンドだけ!
  205. 205. Backup / Restore コマンド Nextscape Inc. 207 PS C:¥> # バックアップ先のStorageのContextを取得する PS C:> $storageContext = New-AzureStorageContext -StorageAccountName "ContosoStorage" -StorageAccountKey $storageKey PS C:¥> PS C:¥> # 復元実行 PS C:> Restore-AzureRmApiManagement ` >> -ResourceGroupName "ContosoGroup" ` >> -Name "RestoredContosoApi" ` >> -StorageContext $storageContext ` >> -SourceContainerName "ContosoBackups" ` >> -SourceBlobName "ContosoBackup.apimbackup" PowerShell による復元方法(こっちも2つのコマンドだけ。書き方ほぼ同じ) • Restore してみる • 復元先の API Managementインスタンスはあらかじめ作成しておくこと • Backup時と同じインスタンスレベル(Dev, Basic, Std, Premium)にすること • Restoreはめっちゃ時間かかる。15分~45分ぐらい
  206. 206. APIの設定に限定した Backup / Restore機能 ImportでAPI のコピーが可能(違うAPIMインスタンスへのImportもOK) Azure Portal, REST API, Powershellコマンドのいずれかで実行可能 バックアップデータはファイルダウンロードしてローカルに格納 (Azure上に格納ではない) Importかなり早い(数秒) API の Export / Import Nextscape Inc. 208
  207. 207. Nextscape Inc. 209 • Portalで API を Exportしてみる API の Export / Import
  208. 208. Nextscape Inc. 210 • Export形式を選択する API の Export / Import
  209. 209. Nextscape Inc. 211 • Open API形式を選んだ場合、こんな内容ファイルがダウンロードされる API の Export / Import { "swagger": "2.0", "info": { "title": "Echo API", "version": "1.0" }, "host": "nsuesaka2.azure-api.net", "basePath": "/echo", "schemes": [ "https" ], … "paths": { "/resource": { "get": { "description": "A demonstration of a GET call on a sample resource. …", "operationId": "retrieve-resource", "summary": "Retrieve resource", "parameters": [ { "name": "param1", "in": "query", "description": "A sample parameter that is required and has …", "required": true,
  210. 210. Nextscape Inc. 212 • Import でAPIをコピーしてみる • titleをImport先の他のAPIと重複しないように修正する • basePathは他のAPIと重複しても気にしないでいい(Import 時に反映されない) API の Export / Import { "swagger": "2.0", "info": { "title": "Echo API2", "version": "1.0" }, "host": "nsuesaka2.azure-api.net", "basePath": "/echo", "schemes": [ "https" ], … 「Echo API」→ 「Echo API2」
  211. 211. Nextscape Inc. 213 • Blank APIテンプレートで APIを新規に作成する API の Export / Import • Display Nameに適当な値を入れる。どうせImportすると上書 きされるので、なんでもOK • API URL suffix とは前頁の basePathのこと。他APIと重複しない 値を設定する必要がある。(後から変更可能)
  212. 212. Nextscape Inc. 214 • 今作ったAPI の Importをクリックし、Import形式を選ぶ API の Export / Import
  213. 213. Nextscape Inc. 215 • 「Select a file」でさっき修正したファイルを選ぶ API の Export / Import
  214. 214. Nextscape Inc. 216 • Import して APIがコピーされた API の Export / Import
  215. 215. Nextscape Inc. 217 • Import した APIの定義を見てみる API の Export / Import { "swagger": "2.0", "info": { "title": "Echo API2", "version": "1.0" }, "host": "nsuesaka2.azure-api.net", "basePath": "/fuga", "schemes": [ "https" ], … "paths": { "/resource": { "get": { "description": "A demonstration of a GET call on a sample resource. …", "operationId": "retrieve-resource", "summary": "Retrieve resource", "parameters": [ { "name": "param1", "in": "query", "description": "A sample parameter that is required and has …", API作成時につけた API URL suffix
  216. 216. API, Policy, 成果物、グループの設定情報がファイル形式(json)で APIM内部の Git Repositoryに存在する Git へ Pushすると、 APIM のRepositoryからAPIMへDeployするらしい (WebAppsとそっくりな動作だ) 同じインスタンスに対するBackup/ Restoreのみ? ユーザー、サブスクリプション、仮想ネットワークの接続設定はフ jsonファイルに書き込まれていない(Restore されない) Git の Repository を Clone する Nextscape Inc. 218
  217. 217. Nextscape Inc. 219 • まず、Git へ APIM の情報を Commit する Git の Repository を Clone する
  218. 218. Nextscape Inc. 220 • コミットされた Git の Repository を Clone する
  219. 219. Nextscape Inc. 221 • Clone するためのアクセス資格情報を取得する Git の Repository を Clone する
  220. 220. Nextscape Inc. 222 • Git Bash で Clone するとこんな感じ(普通の git cloneでしかない) Git の Repository を Clone する
  221. 221. Nextscape Inc. 223 • Cloneした結果のWorking Treeはこんな感じ Git の Repository を Clone する
  222. 222. Nextscape Inc. 224 • ローカルの Clone から、API Managementへ反映 • ローカルから Push し、その後API Management へデプロイする (Push だけじゃ反映されないので注意!) Git の Repository を Clone する Pushしてから デプロイ
  223. 223. Nextscape Inc. 225 異なるAPI Management インスタンスへ Push&Deployできるのか実験 Git の Repository を Clone する Loggerを全部削除すれば、できるのかも・・・。試していない • remote 先を 異なる APIM にして git push --force で無理やりPush&Deploy • Push 先の構成も git clone して、ローカルで置き換えてから Push&Deploy 次の2つを試し たがNGだった

×