Movatterモバイル変換

Azure API Management2018/11/28第14回 NS Study上坂貴志(@takashiuesaka)俺的マニュアル

自己紹介上坂貴志• うえさかたかしTwitter• @takashiuesaka• Facebookは開店休業状態Microsoft MVP• Microsoft Azure 2015年～仕事• マネージャー、プリセールス、エバンジェリスト最近の興味• アジャイル、DDD、エンジニアトレーニング、k8s、DevOps、.NET Core、Frontendフレームワーク、node.jsNextscape Inc. 2

最近はこんなことしてました3Nextscape Inc.

NEXTSCAPE4HoloLensアプリ作ろう DDDやろう Scrumでやろう！SESやっていないので、自社で開発100%ですよ只今、PM・エンジニア積極採用中ですNextscape Inc.

Nextscape Inc. 5今日の内容

API ManagementとはWhat is API Management?

• HTTPベースのAPIを外部に公開する時に必要な仕組みを一通り揃えたPaaSです。• APIとそれを呼び出すClientとの間に挟み込むようにDeployします。API ManagementとはAPI(Backend)(Publisher)Client(FrontEnd)(Consumer)APIManagementNextscape Inc. 7

• 一般的にAPI公開時に求められる以下のようなシナリオに対応できます。API Managementとは外部の開発者に対してAPIごとに使用許可を制御したいAPIの使用を無料ユーザー用や有料ユーザーなどに分けて制御したいAPIのバージョンを簡単に管理したい外部の開発者がAPIを呼び出してテストできるページを用意したい• さらにAzure環境ならでは次の要求にも対応できます。VNETで守られたVMで立てたAPIを外部に公開したいVNET内部だけで公開するAPIに対して上記一般的なシナリオ（バージョン管理やテストページの用意など）に対応したいNextscape Inc. 8

API Management 全体像Overview

Developers GuestsカスタムAdminsAPI Management 全体像API ManagementグループAPIサブスクリプションPolicyFrontend Backend Api/path https://～https://<APIM Name>.azure-api.netアクセス制御開発者(ユーザー)N：NOperationsInOutErrPolicyN：N開発者ポータルNextscape Inc. 10API(Backend)(Publisher)Client(FrontEnd)(Consumer)成果物(製品)N：N

Developers GuestsカスタムAdminsN：NAPI Management 全体像API ManagementサブスクリプションPolicyFrontend Backend Api/path https://～https://<APIM Name>.azure-api.netアクセス制御開発者(ユーザー)N：NAPI(Backend)(Publisher)OperationsInOutErrPolicyN：N開発者ポータルClient(FrontEnd)(Consumer)Nextscape Inc. 11API成果物(製品)グループAPI：API Managementから到達できるAPIであればなんでも登録できる。まずはここへ API を登録するところからスタート。PolicyではRequest/Response/Errorに対して処理をC#で書くことができる。

Developers GuestsカスタムAdminsグループAPI Management 全体像API ManagementサブスクリプションPolicyFrontend Backend Api/path https://～https://<APIM Name>.azure-api.netアクセス制御開発者(ユーザー)N：NOperationsInOutErrPolicyN：N開発者ポータルNextscape Inc. 12API(Backend)(Publisher)Client(FrontEnd)(Consumer) APIN：N成果物(製品/Products)：docsでは「成果物」もしくは「製品」と記載されている。Portalでは「製品」となっているので要注意。APIに対してアクセス制御を行うのが主な役割。APIと成果物はN:Nの関係性。APIは複数の成果物に登録ができる。成果物(製品)

グループDevelopers GuestsカスタムAdminsAPI Management 全体像API ManagementサブスクリプションPolicyFrontend Backend Api/path https://～https://<APIM Name>.azure-api.netアクセス制御開発者(ユーザー)N：NOperationsInOutErrPolicyN：N開発者ポータルNextscape Inc. 13API(Backend)(Publisher)Client(FrontEnd)(Consumer) APIグループ：開発者は複数の（カスタム）グループに所属することができる。ユーザー登録した開発者は必ずDevelopersグループに所属する。成果物のアクセス制御にグループを登録することで、そのグループに所属する開発者はその成果物を使用することができるようになる。グループと成果物はN:Nで紐づけることができる。成果物(製品)N：N

Developers GuestsカスタムAdminsN：NグループAPI Management 全体像API ManagementサブスクリプションPolicyFrontend Backend Api/path https://～https://<APIM Name>.azure-api.netアクセス制御開発者(ユーザー)N：NOperationsInOutErrPolicyN：N開発者ポータルNextscape Inc. 14API(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を投げることができるので独自実装を頑張ればかなりのことができる。

Developers GuestsカスタムAdminsN：NグループAPI Management 全体像API ManagementサブスクリプションPolicyFrontend Backend Api/path https://～https://<APIM Name>.azure-api.netアクセス制御開発者(ユーザー)N：NOperationsInOutErrPolicyN：N開発者ポータルNextscape Inc. 15API(Backend)(Publisher)Client(FrontEnd)(Consumer) APIアクセス制御：アクセス制御は成果物を使用できるグループを設定することで可能となる。ここでいうアクセス制御とは、開発者（ユーザー）に対してのものであることに注意。Policyによるアクセス制限：成果物にもPolicyが設定できる。API単位より上のスコープでの設定と思えばOK。例えば使用量上限があるプランのAPI群を公開したい場合、そのプラン用の成果物を作成して使用量クォータによる制限のPolicy実装をここに設定することになる。成果物(製品)サブスクリプション：成果物では、開発者（ユーザー）に対して利用許諾の申請を求める設定がある。その設定をONにした場合、開発者＆成果物ごとのサブスクリプションキーが発行され、それをHeaderに入れないとRequestが失敗する。（申請を自動承認するか、手動で承認するか選択）

超基本の使い方Basic usage of API Management

APIを追加するNextscape Inc. 17• Blank APIを選ぶと、自分でOperationを追加する必要がある• 他のやつは定義を読んで自動的にメソッドを追加してくれる（はず）• API作るときは、Swagger入れておくと便利だよってこと

APIを追加したあとの「API」画面Nextscape Inc. 18外部からRequestを受ける入口の設定バックエンドAPIの設定バックエンドAPIへRequestを投げる前のカスタム処理バックエンドAPIからのResponseを返す前のカスタム処理

成果物へAPIを登録するどれか選ぶもしくは事前に作っておくAPIを選ぶNextscape Inc. 19• 製品（成果物）メニューからAPIを登録するAPIの画面から成果物に登録できるようになれば素敵なんだけどなー

• APIを登録しただけだと動かない！• missing subscription key というエラーが出たときの原因は大抵コレ成果物へAPIを紐づけるNextscape Inc. 20GroupAグループアクセス制御開発者(ユーザー)成果物(製品)API既存API新規API成果物に紐づけないと、開発者からは見えない。自分がAdminsグループに所属する管理者の場合、Portalからは見えるが実行時はエラーになる。成果物に紐づいていないので実行するとエラーになる

• 外部ツール使ってもいいけど、APIManagementのテストツールを使ったほうが便利• 自動的にサブスクリプションキーを入れてくれる• Policy実装時には、このツールのTrace機能が必須（詳しくは「ポリシー」の最後にて）• 設定すれば、外部IDProviderのOAuth2.0, OpenIdConnectのTokenを取得させることもできるので、認証が必須のAPIの設定確認やPolicyの実装結果を確認する時に重宝する試しにAPIMを叩くNextscape Inc. 21大変残念なことにテストツールの実行履歴が一切保存されない。Policyの実装時にはちょっと辛い

認証結果の検証• Policyにて実装エラーハンドリング• Policyにて実装ログの出力• Policyにて実装スケーリング• Portal/Powershell/Cliで設定バックアップ• Portal/Powershellにて設定キャッシュ• Portal/Powershellにて設定必要なら追加設定するNextscape Inc. 22

ポリシーPolicy of API Management

• ポリシーは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詳細は後述詳細は後述

• C#の実装方法は２つの形式がある。• どちらも括弧の前に@付ける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もできない）っていうかこれラムダ式だわインテリセンスが効かないんだよね・・・

• Reqeust/Response含めたあらゆる情報はこいつが持っている暗黙的なオブジェクト contextNextscape Inc. 26ContextTimestamp: DateTimeVariables: IReadOnlyDictionary<string, object>ResponseRequestLastErrorHeaders: IReadOnlyDictionary<string, string[]>IpAddress: stringBody※一部抜粋アクセス日時<set-variables>でセットされた値を保持Requestのヘッダー値Request元のIPAddressRequestのBody

• contextは、docsの› 「ハウツーガイド」› ポリシーの定義› ポリシー式› 「コンテキスト変数」セクション• に情報があるcontextの中身を知らないと実装できないNextscape Inc. 27

• ちょっと見方にコツがいる。• 例：Requestの情報がほしい• まず、contextから探す。• context.Requestというプロパティがあるのはわかったが、Requestの型もプロパティもわからない・・・• Requestでこの画面内を検索するcontextの中身を知らないと実装できないNextscape Inc. 28

• context.Requestという項目が見つかった。• このようにすべての情報はこの画面内にあるので検索して探していくcontextの中身を知らないと実装できない• さらにここからUrlの型であるIUrlを検索してみると・・・Nextscape Inc. 29

• IUrlの情報を得ることができる。• context.Request.Url.Path と書くことで、リクエスト時のURLを取得できることがわかった• プロパティ名は大文字小文字区別する（Case-Sensitive）contextの中身を知らないと実装できないNextscape Inc. 30

• サブスクリプションごとに指定期間あたりの呼び出しレートを指定数に制限利用を制限するポリシー<inbound><rate-limitcalls="5“renewal-period="60" /><base /></inbound>Nextscape Inc. 31<inbound><quotacalls="100“bandwidth="40000“renewal-period="604800" /><base /></inbound>• サブスクリプションごとに呼び出し回数と帯域幅クォータの両方またはそのどちらかで制限KBytesSeconds1分に5回まで1週間に100回、もしくは40,000KBまで

• キーごとに指定期間あたりの呼び出しレートを指定数に制限利用を制限するポリシー<inbound><rate-limit-by-keycalls=“5”renewal-period=“60“counter-key=“@(context.Request.IpAddress)” /><base /></inbound>Nextscape Inc. 32<inbound><quotacalls=“100“bandwidth=“40000“renewal-period=“604800”counter-key=“@(context.Request.IpAddress)” /><base /></inbound>• サブスクリプションごとに呼び出し回数と帯域幅クォータの両方またはそのどちらかで制限IPAddress毎に1分に5回までIPAddress毎に1週間に100回、もしくは40,000KBまでcounter-keyへのセットは文字列なんでもOK

• オブジェクトをディクショナリへ格納する• 何かしらの処理の結果を格納する時に使うset-variablesは多用するNextscape Inc. 33<set-variablename="putDate“value="@(context.Timestamp.ToString("R"))" />• ディクショナリはcontext.Variables : IReadOnlyDictionary<string, object>• オブジェクトの取り出し方（GenericsではないのでCast必要）• (cast)context.Variables[“keyName”]putDateはディクショナリのKey名

• 同期リクエストの場合は<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

• 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. 35responseを格納する変数変数値をTraceで表示させるために意味なく他の変数にセットする

• これを埋めていく追加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

• 非同期のリクエストを投げる実装（他は省略）追加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

• テストツールのTraceを見れば、リクエスト先が返したエラー情報が見える。• Ocp-Apim-Traceヘッダにtrueという値を入れておく必要があるが、デフォルトで設定済みなのであまり気にしなくて大丈夫Policyのデバッグ方法Nextscape Inc. 38デフォルトはMessageタブが表示されているので、Traceに切り替えるこの例では、<set-varialble>に設定されたポリシー式を評価した（実行した）結果を表示している。

Globalレベル（API の All APIsに設定する）成果物レベル（製品）API レベル(API の All Operationsに設定する）各Operationsレベルポリシーには階層がある• 上から順に評価される。Nextscape Inc. 39

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>の処理を意味している

• <backend>だけはデフォルトでグローバルレベルに<forward-request>が実装されている。こいつがBackend Apiを呼び出すタグ。<backend>についてNextscape Inc. 41成果物、API、Operationsの全てのレベルのデフォルト実装の<backend>の<base />は、削除するとBackend APIが呼び出されなくなるので注意してねOperationsレベルの例グローバルレベルの例

• <backend>には１つだけしか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 />を削除

• Visual Studio Code用のスニペットならある・・・けど使えないかな• https://github.com/Azure/api-management-policy-snippetsポリシーの素敵なエディタはないのかNextscape Inc. 43

開発者とグループDevelopers and Group

開発者とグループ• グループは成果物とN：Nで紐づけることで開発者へのAPI公開を制御するグループアクセス制御成果物(製品)アクセス制御GroupAGroupBAPIAPIAPIAPIAPI開発者全部のAPI使用可下２つのAPIのみ使用可Nextscape Inc. 45

開発者とグループ• デフォルトで用意されているグループは３つ• Administrators, Develpers, Guests• 開発者を新規追加すると、デフォルトでDevelopersグループ所属になるNextscape Inc. 46開発者(ユーザー)DevelopersGuestsAdminsデフォルトグループGroupAGroupBカスタムグループ開発者をPortalから追加しても、開発者ポータルから開発者自身がサインアップしても、必ずDevelpersグループの所属になる

Addボタンがない！開発者とグループ• あれ、Admin, Guestへのユーザー追加はどうやるのか？• Powershellなら追加できるっていう訳じゃなかったNextscape Inc. 47

• 共同作成者以上の権限を持つAzureユーザーは自動的に全員Adminグループに紐づけられる• Adminsグループは新規作成の成果物のアクセス制御に自動的に登録される開発者とグループグループアクセス制御開発者(ユーザー)成果物(製品)APIAPIアクセス制御DevelopersGuestsAdminsデフォルトグループAzure ユーザーAPIM作成者APIM共同作成者GroupAGroupBカスタムグループ自動的に紐づけられるAzureユーザーが紐づけるNextscape Inc. 48• Guestsグループはユーザー登録をしていない匿名ユーザーが暗黙的に所属するグループ（登録前にお試しに使ってもらいたい場合などはGuestsグループに紐づける＝登録しない）APIAPIAPI

API Manegement Role別機能差APIM作成者 or APIM 共同作成者 APIM Operator Role APIM Reader RolePortal フル権限参照のみ。変更設定できるのはスケールアップ・ダウン、SSL、カスタムドメインの設定ぐらいメトリックス参照できるぐらい。その他は参照すらできない開発者ポータルフル権限 × ×所属Group Administrator Guest Guest• APIMの作成者、またはAPIM 共同作成者ロールの権限があるAzureユーザーは、暗黙的にAdministratorグループに所属する（共同作成者は画面にユーザーとしては表示されない）• APIM Service Reader Role, Operator Roleの権限をもつAzureユーザー、もしくはユーザー登録をしていない（認証していない）場合は暗黙的にGuestグループに所属するNextscape Inc. 49

• カスタムグループへの開発者の登録はPortalで管理者が行う以外の手段がない• こんな設定にしてあったら、自動的に登録してくれないのかな？カスタムグループへの開発者の登録は手動だけカスタムサブスクリプションアクセス制御Policy開発者ポータル成果物(製品) グループDevelopers１.サブスク申請が承認されたら２.カスタムグループに自動的に登録されないのか１２Nextscape Inc. 50• 承認が必要な成果物を作る• 成果物に対してカスタムグループを紐づけておく• 開発者ポータルからこの成果物に対してサブスクリプション申請• Portalからサブスクリプションを承認• 紐づいたカスタムグループにユーザが登録されるか試すならこんな手順

試してみたNextscape Inc. 51• 承認が必要な成果物を作る• 成果物に対してカスタムグループを紐づけておく• 開発者ポータルからこの成果物に対してサブスクリプション申請• Portalからサブスクリプションを承認• 紐づいたカスタムグループにユーザが登録されるか

試してみたNextscape Inc. 52• 承認が必要な成果物を作る• 成果物に対してカスタムグループを紐づけておく• 開発者ポータルからこの成果物に対してサブスクリプション申請• Portalからサブスクリプションを承認• 紐づいたカスタムグループにユーザが登録されるかDeveloperグループも紐づけておかないと、開発者ポータルに成果物が表示されない

• 開発者ポータルで申請中になったことを確認試してみたNextscape Inc. 54

• 申請が許可されてSucscription Keyが発行された試してみたNextscape Inc. 56

試してみたNextscape Inc. 57• 承認が必要な成果物を作る• 成果物に対してカスタムグループを紐づけておく• 開発者ポータルからこの成果物に対してサブスクリプション申請• Portalからサブスクリプションを承認• 紐づいたカスタムグループにユーザが登録されるか追加されなかった・・・残念

サブスクリプションSubscription

• 開発者への成果物に対する利用許諾のこと。• 登録したユーザーだけが使用できるようにしたい場合の設定。• Front APIへのRequestにsubscription keyのセットを必須にする• 開発者は利用許諾の申請を開発者ポータルより行う。（Azureポータルじゃない）サブスクリプションNextscape Inc. 59• 申請を自動承認にした場合は、申請されたら即時 subscription key が発行される。• 要承認にした場合は、Portalから管理者が手動で承認する必要がある。• 利用許諾の申請が発生してもメールが飛ぶ、Webhookを叩くなどのメンションを飛ばすことができない（不便すぎて困る）

• Portalに• 「サブスクリプションの追加」• 「サブスクライバーの追加」• の2つの表記があり、用途の違いがわからなくて混乱しちゃうので整理しておく。サブスクリプション「サブスクリプションの追加」とは、成果物（製品）と開発者（ユーザー）の両方を指定して承認することNextscape Inc. 60

• 成果物（製品）からサブスクリプションを選んだ時には、「サブスクライバーの追加」というメニューがある。サブスクリプション「サブスクライバーの追加」とは、開発者（ユーザー）だけを指定して承認することNextscape Inc. 61

• ユーザーが開発者ポータルからサブスクライブする要承認にした時のサブクライブの挙動Nextscape Inc. 62

• Subscription name（利用許諾名）は自分で入力する（謎仕様）要承認にした時のサブクライブの挙動Nextscape Inc. 63

• リクエストしたので承認待ち状態になる要承認にした時のサブクライブの挙動Nextscape Inc. 64

• Azure Portalで見ると、承認待ち状態になっている。• なぜか「状態」は「送信済み」という表記。（「承認待ち」にしてほしい・・・）• 「サブスクリプションのアクティブ化」をクリックする。要承認にした時のサブクライブの挙動Nextscape Inc. 65

• 開発者ポータルを読み込みなおすと、Subscription Keyが発行されている要承認にした時のサブクライブの挙動Nextscape Inc. 66

開発者ポータルDevelopers Portal※docsでは「開発者」を「ユーザー」と表記しているページも多いので注意

https://<APIMName>.portal. azure-api.net開発者ポータルのURLは管理者権限があるならここから遷移すればいいNextscape Inc. 68

開発者ポータルの見た目（デザイン可能）Nextscape Inc. 69

• 開発者が• 自らユーザーとして登録する機能• 開発者が使いたい成果物（APIを含んでいる）に対して利用許諾を申請する機能• APIをお手軽に試すテスト機能• 不具合を報告する機能（管理者にはmailが飛んでくる）• などを持つ、開発者のための画面。• APIMagementインスタンスとは全く別のリソースと思ったほうが良い• 開発者ポータルはAPIMagementとは無関係のWebクライアントとして認識したほうがdocsが読みやすい• AzurePortalでは、（基本的に）開発者ポータルへのログインユーザーの権限管理しかしない• 権限管理以外だと、開発者ポータルがAPIMgmtに対してRequestする前に外部IDProviderからid_token（JWT）を得る、もしくは認証サーバーからaccess_tokenを得るための機能のための設定をするぐらい（ややこしいので後述する）そもそも開発者ポータルとは何かNextscape Inc. 70

1.Portalから手動で追加する2.Portalからメールアドレスを入力して招待する3.開発者ポータルから自分でサインアップ（要セットアップ）開発者を追加する方法は？３つの方法があるNextscape Inc. 71

• Portalからのユーザー追加は ID/PW認証のみ1.Portalから手動で追加するNextscape Inc. 72

2.Portalからメールアドレスを入力して招待するNextscape Inc. 73

2.Portalからメールアドレスを入力して招待するNextscape Inc. 74

3.開発者ポータルから自分でサインアップNextscape Inc. 75

• Portalにログインできて、かつユーザーを管理する権限を付与されているユーザーにしかできないPortalから手動で追加する• 開発者ポータルのID/PWを使ったサインアップ画面へのリンクがメールで飛ぶ• Portalにログインできて、かつユーザーを管理する権限を付与されているユーザーにしかできない• ID/PWサインアップのセットアップが必須（デフォルトでID/PW認証はセットアップされている）Portalからメールアドレスを入力して招待する• 運用者は開発者ポータルのURLを送るだけ良いので一番楽• ID/PWを使ってサインアップ、もしくは• 外部IDProvider(AzureAD, Facebook, Twitterなど)を使って認証させることができる開発者ポータルから開発者が自分でサインアップ開発者を追加する方法は？まとめNextscape Inc. 79

セキュリティ->ユーザーで認証方式を登録するNextscape Inc. 80開発者ポータルサインアップのセットアップ方法は？

Nextscape Inc. 81するとサインアップ画面が現れる開発者ポータルサインアップのセットアップ方法は？これがこうなるでも、これID/PWの場合だけ！

サインアップだとこうなっちゃうサインインなら外部のIDProviderが表示される外部のIDProvider（FacebookとかTwiterとか）を有効にしたときはサインインを使わないといけないので注意！開発者ポータルサインアップのセットアップ方法は？Nextscape Inc. 82開発者ポータルのカスタマイズが必須（別に難しくはない）

• 認証の種類にFacebookって出るFacebookで認証してサインアップするとだから何ってわけじゃないけど・・・。Nextscape Inc. 83

Nextscape Inc. 84開発者ポータルって日本語化できないの？完璧じゃないけど一応できる。もうすぐ無くなってしまう発行者ポータルより設定可能（Portalで設定できるようになるはず）

API Managementでいうセキュリティは複数個所あるセキュリティコンシューマパブリッシャーAPI Management開発者ポータル１２APIClient３４Nextscape Inc. 86

Nextscape Inc. 87用途が混在していてわかりにくいので要注意Portalのセキュリティセクション開発者ポータルの認証方式の設定• クライアント認証の検証時に使う証明書をUploadする• APIを呼び出す時に使う証明書をUploadする（どちらもUploadだけじゃダメで、Policyにて実装が必要）独自に実装した開発者認証、成果物のサブスクリプションを行う認証サーバーの設定• 開発者ポータルの認証方式の設定• 開発者ポータルからAPIをテストする時にTokenを取得するために必要な認可サーバー(or IDProvider)の設定1 2334APIClient3「開発者ポータル」で説明済み324は証明書の検証もできるが、PolicyでJWTの検証をするのがメイン11説明済み

• これをセットアップすると、開発者ポータルでTokanを取得できるようになる、というだけ！• 勘違いしがちなのは、これをセットアップするとなんかよくわかんないけど外部の認証サーバー（IDProvider）を使って認証してくれるようになるんだ、なんて思わないこと！• なので、 APIのエンドポイントがむき出しの場合にAPI側で認証結果(JWTとか)を検証する実装をさぼれる訳じゃない、ということ• API側がFunctionsみたいにアクセスキーがある場合はアクセスキーの検証だけでOKとして、認証結果の検証を実装しなくてもいいのかは判断が必要• APIがVNET内部にDeployしてあって外部からの攻撃はない、という場合なら気にしなくていいかもOAuth2.0, OpenIdConnectの使い方• 開発者ポータルの認証方式の設定• 開発者ポータルからAPIをテストする時にTokenを取得するために必要な認可サーバー(or IDProvider)の設定43Nextscape Inc. 881 23APIClient 4説明済み

開発者ポータルでOAuth2.0のTokenを取得するNextscape Inc. 89AzureADという名前を付けた

• APIにOAuth2.0を使用するようにセットアップ（これが誤解させる元凶）開発者ポータルでOAuth2.0のTokenを取得するNextscape Inc. 90

Try it をクリックして開発者ポータルでOAuth2.0のTokenを取得するNextscape Inc. 91承認コードを選択する

• ログインダイアログがポップアップ（ログインしていなかった場合）• アクセス許可の承認を求められる開発者ポータルでOAuth2.0のTokenを取得するNextscape Inc. 92• アクセストークンを取得して保持したことがわかる

PortalのTest機能は、サブスクリプションキーを自動的にHeaderにセットする機能しかないOAuth2.0, OpenIdConnectの使い方• PortalのTest機能にはアクセストークンを取得する機能はないので間違えないように！（開発者ポータルでやること！）Nextscape Inc. 93

• API Managementは認証・認可（承認）の機能は持っていない。あくまでJWTの検証をするPolicyがデフォルトで用意されているだけ• JWTを検証する、ということはIDProviderはAzureAD、B2Cだけしか使えないわけじゃない。OpenIdConnectをサポートするIDProviderであればなんでも大丈夫validate-jwt 1 23APIClient 4は証明書の検証もできるが、PolicyでJWTの検証をするのがメイン1ClientAPI MgmtB2CIDProviderJWTJWT• OAuth2.0ではなくOpenId Connectであることに注意。OAuth2.0の返すaccess_tokenは仕様が策定されてないし、通常JWTは使用されない。（ランダム文字列）• OpenId Connectであれば、id_tokenがJWTで返却される。• id_tokenの中にClameが格納されている。Nextscape Inc. 94

• 最終的に次の構成を組むvalidate-jwtを試す（敢えてAzureAD以外で）Client API MgmtJWTAPIJWTValidateOpenId Connect• その前にまずはローカル環境JWTを取得する実装をして、JWTのValidationもやってみるClientJWTJWTValidateJWTOpenId Connect JWTClientNextscape Inc. 95

• https://console.developers.google.com• プロジェクトを作る• 既にあるならそれでもいいGoogle Developers ConsoleNextscape Inc. 96

Google+ APIを追加するNextscape Inc. 97

• 認証にはこのAPIの追加が必要、というBlogもあれば、不要、というBlogもある• 今回はそこがポイントじゃないので取り合ず追加しとく• （多分追加は不要だと思われる。オワコンだし）Google+ APIを追加するNextscape Inc. 98

認証情報を作るNextscape Inc. 99

認証情報を作るNextscape Inc. 100

• アプリケーション名を入れる• 他の項目はそのままでいい認証情報を作るNextscape Inc. 101

認証情報を作る認証後にGoogleAPIからid_tokenが戻ってくるリダイレクト先のURI。まだWeb画面作っていないので後で入力するNextscape Inc. 102

• メモらなくてもいつでも確認できる認証情報を作るNextscape Inc. 103

• ASP.NET Core 2.1で作る• VS, VSCodeのどっちでもいいけど個人認証ありでプロジェクトを作る• dotnet new mvc --auth Individual (VSCodeの場合)Webクライアントを作るJWTJWTValidateOpenId Connect JWTNextscape Inc. 104

• 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

launchSettings.jsonは、Propertiesフォルダ内にあるSSL Portを確認してRedirectURlをGoogleに登録Nextscape Inc. 107

• ミドルウェアを使った場合、RedirectURIのリソース名はsignin-googleで固定。今回はhttps://localhost:44315/signin-google となる• FacebookやAzureADの場合は、signin-xxxのxxxが変わる• このRedirectURIが一致しないとエラーになるので間違えないように• 認証情報 -> 作った認証情報右にある鉛筆アイコンをクリックするSSL Portを確認してRedirectURlをGoogleに登録Nextscape Inc. 108

• RedirectURIは複数登録できるので便利（本番、テスト用にそれぞれ作る必要がない）SSL Portを確認してRedirectURlをGoogleに登録Nextscape Inc. 109

画面を動かして確認Nextscape Inc. 110

または画面を動かして確認Nextscape Inc. 111

画面を動かして確認Nextscape Inc. 112

ログイン成功Nextscape Inc. 113ログイン時のメルアドが表示される

• 本当はControllerからWebAPIを呼ぶ実装にしたかったが、取得したid_tokenをControllerに渡せないため、手動でid_tokenを取得しておいてPOSTMANを使ってWebAPIを叩くことにする。id_tokenの取得ブレイクポイントを置いて、このid_token変数の中身を見るNextscape Inc. 115

WebAPIを作るJWTJWTValidateOpenId Connect JWT• ASP.NET Core 2.1で作る• VS, VSCodeのどっちでもいいけど個人認証ありでプロジェクトを作る• dotnet new webapi (VSCodeの場合)Nextscape Inc. 116

• services.AddMvcメソッドの上に実装するJWTのValidation実装をStartupクラスにするNextscape Inc. 117services.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 DevConsoleで認証作成した結果をセットする

• StartupクラスのConfigureメソッドに次の一行を実装認証ミドルウェアを有効化if (env.IsDevelopment()){app.UseDeveloperExceptionPage();}else{app.UseHsts();}app.UseAuthentication();app.UseHttpsRedirection();app.UseMvc();Nextscape Inc. 118

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

• httpsの検証をOffにしておくPOSTMANでAPIを叩いてみるNextscape Inc. 120

最初は401になるのが正解Nextscape Inc. 121

• ちゃんと結果がとれたJWTをAuthヘッダーに入れて呼び出すNextscape Inc. 122

間にAPI Managementを挟むAPI MgmtJWTValidateClient JWTJWT ValidateOpenId ConnectJWTAPI手動JWTセットClient JWTJWT ValidateOpenId ConnectJWTAPI手動JWTセットNextscape Inc. 123

• 動作確認OKWebAPIをAzure WebAppsにデプロイしたNextscape Inc. 124

• サブスクリプションは不要にしてあるWebAppsをAPIMのAPIに登録して成果物と紐づけNextscape Inc. 125

validate-jwtを実装する（APIレベルに対して）Nextscape Inc. 126

• 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></audience></audiences><issuers><issuer>accounts.google.com</issuer><issuer>https://accounts.google.com</issuer></issuers></validate-jwt></inbound>Nextscape Inc. 127

• JWTなしの場合確認Nextscape Inc. 128

• curl https://accounts.google.com/.well-known/openid-configuration（おまけ）GoogleのエンドポイントはDiscovery Docから取得Nextscape Inc. 130

• https://www.googleapis.com/oauth2/v3/certs• 1時間に１回変わるそうなので、自前でValidateするとキツそう（おまけ）Googleと検証側で共有する公開鍵Nextscape Inc. 131

• Clientが渡してきたクライアント証明書を検証する実装証明書の使い方• クライアント認証の検証時に使う証明書をUploadする• APIを呼び出す時に使う証明書をUploadする（どちらもUploadだけじゃダメで、Policyにて実装が必要）21<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. 1321 23APIClient 4

• APIを呼び出す時にクライアント証明書を渡す実装方法証明書の使い方• クライアント認証の検証時に使う証明書をUploadする• APIを呼び出す時に使う証明書をUploadする（どちらもUploadだけじゃダメで、Policyにて実装が必要）21<inbound><authentication-certificate thumbprint="thumbprint" /><base /></inbound>※未検証Nextscape Inc. 1331 23APIClient 4

構成パターンConstruction pattern

• 公開エンドポイントのセキュリティに注意。• APIMgmtのPublicIPは、自分からインスタンスを消さない限り固定なので、ホワイトリスト対応が可能なPaaSならそれでOKとして良いかも公開されたエンドポイントのProxyにする構成コンシューマClientAzure On-PremissAPIMgmt開発者ポータルDMZVNETPublic IPWebApps Functions開発者公開されたエンドポイントNextscape Inc. 135

• APIMgmtからVNET内部のリソースにアクセス可能です。• ServiceEndpointに接続したリソースは403エラーになるのでNG（確認した）VNETのリソースを外部公開する構成コンシューマClientAPIServerVNETSubnetSubnetAPIMgmtAPIMgmtが接続する専用のサブネットが必要。このサブネットには他のリソースが割り当てられていてはNG最小/29開発者Azure On-Premiss開発者ポータルVPNGatewayNextscape Inc. 136

• オンプレからのAPIアクセスも外を通らない• DNSに注意がいる（DNS立てないと名前解決全滅。Portalのテストすら動かない！）内部だけに公開する構成コンシューマClientAPIServerVNETSubnetSubnetAPIMgmt開発者ポータル最小/29Azure On-Premiss開発者VPNGateway開発者ポータルは、外部からも内部からもアクセスできなくなる。VNET内部にデプロイされるわけではないので、内部IPが割り当てられない。Nextscape Inc. 137

• Portalのテストすら動かないAPIMgmtをVNET内部に置いた場合名前解決に失敗しているNextscape Inc. 138

DevまたはPremiumレベル（月額319,064！）でないと「仮想ネットワーク」は表示されない（表示されない＝VNETに接続できない）VNETにつなげるにはPremiumレベル必須Nextscape Inc. 139

バージョン管理Version Management

• API Managementではリビジョンとバージョンの２つの機能でAPIのメンテナンスすることができるリビジョンとバージョンNextscape Inc. 141リビジョン• WebAppsのスロット機能ととても良く似た仕組み。API単位に作成可能。バージョン• 異なるバージョンのAPIを同時に公開するためのもの。• リビジョンごとに別API別URLになる• 複数のリビジョンを作成できる• リビジョンを指定して本番APIに切り替え

リビジョン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/resourceRevision=2のURLhttps://<resourceName>.azure-api.net/echo;rev=2/resourceRevision=1のURLhttps://<resourceName>.azure-api.net/echo;rev=1/resourceメインのURLhttps://<resourceName>.azure-api.net/echo/resourceRevision=2をメインに切り替え

リビジョンNextscape Inc. 143• Revsionが入ったURLは、知っていれば誰でもアクセスできてしまうので、サブスクリプションキー必須にするなどしてAPIを守るようにすることリビジョン使用時の注意• 本番で稼働しているAPI定義やPoliciyに影響を与えることなく、安全に変更することができる• APIM定義をPublishする前に稼働確認ができる• 切り替え時に変更点を記載すると開発者ポータルに表示できるため、開発者に対して何をしたのかアナウンスできる• リビジョンの切り替えがすぐ反映されるので、問題があったらすぐにロールバックできる（即時反映なので、DNS切り替えではないみたい）リビジョンを使用する理由

リビジョンの作成方法Nextscape Inc. 144

• リビジョン一覧画面に表示される説明文。後から修正できるリビジョンの作成方法Nextscape Inc. 145

• RevisionのIDは自動採番されるリビジョンの作成方法URLの例https://<resourceName>.azure-api.net/echo;rev=2/resource?param1=sampleNextscape Inc. 146

このリビジョンをメインとして公開するリビジョンの管理Nextscape Inc. 147このリビジョンを削除するこのリビジョンを非公開にする

Nextscape Inc. 148• 特定のリビジョンを公開しようとするとこんなダイアログがあがるAPIの更新ログ

Nextscape Inc. 149• 書いた内容が開発者ポータルに公開されるAPIの更新ログ

• 例 /v1, /ver1パス• 例 ?ver=1, ?api-ver=2, ?api-version=2018-11-01クエリ文字列• 例 ver:v1, api-ver:2, api-ver:2018-11-01HeaderバージョンNextscape Inc. 150同時に複数のバージョンのAPIを公開する機能バージョン文字列は、好きな文字列が使用可能（数字、日付、名前など）バージョンの差異はバージョン文字列を次の3種類のいずれかに埋め込む

• APIの各バージョンは開発者ポータルで一覧で表示されるバージョンNextscape Inc. 151

• API公開後にバージョニングを開始すると、最初のバージョンのURLを変更できない（ユーザーに影響がある）ため、混乱を招いてしまう。バージョン使用時の注意点バージョンNextscape Inc. 152最初のバージョンのURLhttps://<resourceName>.azure-api.net/<api>/<operation>バージョニングしたURLhtps://<resourceName>.azure-api.net/<api>/v2/<operation>• 破壊的な更新をリリースすることができるバージョンを使用する理由この２つのURLが同時に使用可能な状態

Nextscape Inc. 153この例ではblank APIだが、1. Fullを選択2. Version this API?にチェックでバージョニング開始となるのは他のテンプレートを選んでも同じAPI作成時にバージョニングを開始する

API作成後でバージョニングを開始するNextscape Inc. 154

API作成後でバージョニングを開始するNextscape Inc. 155

Nextscape Inc. 156バージョニング開始前API。何もしなければURLは元のままだが、このAPIにバージョンを後から追加もできる※URLが変わるということ。※適用は慎重に！（ユーザーに影響）

だったらバージョニングは、最初からするべき公開前であれば、影響なく後からバージョニングを開始できるので慌てて作り直さないことどうやって使い分けするのかバージョンとリビジョンは目的が異なるため、どちらかだけ使用するのでもいいが、どう考えても両方使用することになるバージョンとリビジョンの使い方Nextscape Inc. 1571. 次のバージョンを作る2. 最初のAPIをバージョンを指定3. 次のバージョンを消す

Nextscape Inc. 158docs では透過的バージョンアップという手法が提案されている• https://docs.microsoft.com/ja-jp/azure/api-management/api-management-sample-cache-by-key#transparent-versioning• APIM側のバージョンアップにクライアントが合わせるのではなく、クライアントに合わせてAPIM側がバージョンを切り替えるやり方のことらしいクライアントに影響を与えないバージョンアップ戦略APIAPIM通常はクライアントがバージョンを選択するAPIAPIM透過的バージョンアップはAPIMがバージョンを選択するBackendAPIv1v2v3v1v2v3BackendAPIv1v2v3

Nextscape Inc. 159docsに記載されているサンプルの図解• どのクライアントがアクセスしてきたのかをSubscriptionKeyで判定する方法透過的バージョンアップの構成APIAPIMBackendAPIv1v2v31.HeaderにSubscriptionKeyを入れてRequestバージョン管理2. SubscriptionKeyをキーにキャッシュにデータがあるかを確認3. データがキャッシュがなかったら、SubscriptionKeyをキーに外部からバージョンを取得し、キャッシュへ格納4.BackendAPIのURLを取得したバージョンに書き換えキャッシュにはSubscriptionKeyをキーにバージョンが格納されているKeyValueのキャッシュ機能がAPIMにはある（フラグメントキャッシュ）

Nextscape Inc. 160docs の日本語が難しいが、恐らくこういうことが言いたいんだと思われる• https://docs.microsoft.com/ja-jp/azure/api-management/api-management-sample-cache-by-key#tenant-isolationバックエンドの障害対応と段階的ロールアウトAPIAPIMBackendAPIv1BackendAPIv1BackendAPIv1v1同じバージョンのBackendAPIを複数用意しておき、クライアントがどのBackendAPIにアクセスするのかをAPIMが判定するように設計する• 設定方法は透過的バージョンアップとほぼ同じ• BackendAPIのハードウェア障害が起こった時に、影響があるクライアントが限定される• BackendAPIのハードウェアごとにバージョンアップをしていくことで段階的にロールアウトが可能となる（似非カナリアリリース）

API Management のエラー処理Error handling

API Management のエラー処理Nextscape Inc. 162• API Mamagementでいうエラーは、Policyで発生したエラーと、Backend APIで発生したエラーと二種類あることを意識しておくことPolicyInOutErrAPI(Backend)(Publisher)Client(FrontEnd)(Consumer)BackendBackendAPIのResponseが4xx, 5xxの場合<outbound>でエラーハンドリングPolicyがエラーをThrowの場合<on-error>でハンドリングAPI Management

• <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>セクションを通らないので注意

• エラー処理の例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分間に５回までのリクエスト制限わざと１分以内に６回リクエストしたPolicyが返却した独自のStatusCode

• エラー処理を実装した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を返却するわざと１分以内に６回リクエストした※API Managementでは、Custom の Http StatusCodeは101～599の範囲のみ設定可能エラー詳細をHeaderへセット（全実装は次ページ）なぜかReasonを表示してくれない・・・

• エラーの詳細情報を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への出力だと確実に出力される保証がない

• 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を返却する

APIMで取得できるログの種類ロギング• Azureのリソースが出力する自身のデータ。リソースの種類によって出力されるデータが異なる。APIMの場合、TotalRequests数やFailedRequests数など。• メトリックの数値を元にアラートを設定することが多い。メトリックスNextscape Inc. 169

• Azureのリソースを外部から操作した操作ログ。APIMの場合、”Create API”や”Add API toProduct”など。アクティビティロギングAPIMで取得できるログの種類Nextscape Inc. 170

• 監査・トラブルシューティングに使用するためにAzureリソースが出力するログ。• API Management は、個々の API 要求についての診断ログを数分に1回出力する。リアルタイム性はない• 事前定義されたスキーマしか出力できない診断ログロギングAPIMで取得できるログの種類Nextscape Inc. 171

• EventHubsへ出力する設定をやってみたロギングNextscape Inc. 172これはEventHubsのポリシー。ポリシー毎にアクセス権が設定されている。これにCheckを入れないとEventHubsへ診断ログが出力されない1Requestごとの診断ログ。5分に1回、1分毎5分間のログを出力（※ Requestがあった場合だけ）

• 診断ログのEventHubsへの出力• GatewayLog（1Requestについてのログ）は約１分ごとに出力されるが、観察していると消失するログもある• GatewayRequests,Capacity（メトリック）はRequestがあった時は1分間隔のログを5分間分、5分に1回出力する• Docsには「1時間に1回出力する」と記載があるが違うみたいロギング診断ログをEventHubsへ出力する設定をして、StreamAnalitycs->Functionsへと接続したNextscape Inc. 1731分ずつ、5分間のログ

• 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/*******-****-****-…"}エラーを出力したポリシーポリシーのスコープポリシーを実装したセクション• この情報以上は出力できないので、例えばこのリクエストは誰？という特定はできない

• フルカスタマイズしたログを出力したいならこのポリシーを使う• 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;SharedAccessKey=<key>" `-Description “Test logger"設定先のAPI Management のContextオブジェクトを取得する任意の文字列任意の文字列EventHub名API ManagementにEventHub対応のロガーを作成

API Managementに設定したロガーの一覧EventHubへ出力するポリシーNextscape Inc. 176Get-AzureRmApiManagementLogger `-Context $apimContext• おまけのコマンド一覧API Managementに設定したロガーの削除Remove-AzureRmApiManagementLogger `-Context $apimContext `-LoggerId <loggerId>

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から色々引っ張ってくるべし

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“}

Nextscape Inc. 179• EventHubからデータを取得してみるとこんな感じEventHubへ出力するポリシー

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>

Log Analyticsへ接続するNextscape Inc. 181

Nextscape Inc. 182• Log Analyticsへの結果出力は1時間に1回ぐらい？すごく遅いので、名前の通りあくまで分析用Log Analyticsへ接続する通信量

ユニット、という単位でスケールするスケーリング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 東日本の単価。課金は時間単位）• １ユニットの作成には15分～40分かかる※ユニット＝APIMインスタンス、の理解で間違いない

複数リージョンへのデプロイが可能• Premiumレベルの場合のみ設定可能。２リージョン以上へのデプロイでSLAが99.95%になる自動スケール• Standard、Premiumレベルの場合のみ設定可能• ユニットの増加は20分以上かかる• 複数リージョンへデプロイしている場合、自動スケールはプライマリリージョンだけが対象• プライマリリージョン：最初にAPIMを作ったリージョンのことスケーリングNextscape Inc. 185

Nextscape Inc. 186• スケールしてみるスケーリング

Nextscape Inc. 187• 複数リージョンへデプロイしてみる複数リージョンへのデプロイ

Nextscape Inc. 188複数リージョンへのデプロイ

Nextscape Inc. 189パフォーマンスへの影響• BackendAPIは元のリージョンに１つだけだと、プライマリリージョン以外にデプロイされたAPIMはアクセスがある度に異なるリージョンのBackendAPIを叩きに行くため、パフォーマンスが悪い解決方法は２つ• BackendAPIも各リージョンへデプロイし、APIMがデプロイされている場所に応じてBackendAPIを切り替えるようにポリシーを作成する• キャッシュを使う（キャッシュのセクションを参照）複数リージョンへのデプロイの懸念点

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に記載されているもの

Nextscape Inc. 191• なぜかAPIMの自動スケールはAzure Monitorから設定する自動スケール

Nextscape Inc. 192自動スケール

Nextscape Inc. 193自動スケールの設定は、メトリックを基にするか、スケジュールするかの2択。だがインスタンス数の増減に20分以上もかかるので、メトリックを基にするのは現実的じゃない。スケジュールによる設定しか使わないだろう。自動スケール• スケジュールによる自動スケール設定は、条件（condition）を３つ作成する。1つ目はデフォルト設定。

Nextscape Inc. 194• 2つ目の条件スケールアウトの設定例自動スケール• 3つ目の条件スケールインの設定例

キャッシュは２つのポリシーを対で設定する• キャッシュからデータを取得するポリシー 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>開発者キーごとに応答をキャッシュするか開発者グループごとに応答をキャッシュするかキャッシュするポリシーを設定キャッシュを検索するポリシーキャッシュ保持時間を設定キャッシュする単位。複数指定可能

• キャッシュする場所と数CDNとの違いNextscape Inc. 197• 事前キャッシュCDNEdgeサーバーが全世界各地に配置してある。Edgeまでの物理的な距離が近いほどEdgeまでの到達時間は早いためキャッシュしてあればレスポンスは速い。が、キャッシュする場所が多いということはOriginアクセスも意外と多いAPI Managementテナント単位の共有データキャッシュ。（テナント＝作成済みAPIMリソース）が使用されるため、１リージョン１キャッシュ。複数のユニットにスケールアップしても、同じキャッシュデータにアクセス可能。ただし、複数リージョンにデプロイした場合はそれぞれのリージョン別のキャッシュとなるCDN できる。Poralから、もしくはAPIを使用したキャッシュも可能API Management できない。<outbound>ポリシーでキャッシュするので、事前にはできない

• パージCDNとの違いNextscape Inc. 198• キャッシュコントロールCDN任意のタイミングでキャッシュを削除できる。Poralから、もしくはAPIを使用した削除も可能API Management 任意に削除できない。キャッシュ保持経過時間が過ぎるのを待つしかないCDN• クエリ文字列ごとに違うキャッシュにできる• Http-Headerの各種メタごとに違うキャッシュにできるAPI Management CDNと同じ

明示的にKeyを指定して値をキャッシュする機能のことdocsには例として、他のサービスから取得したユーザープロファイルをユーザーIDをKeyにしてキャッシュし、それをResponseに埋め込む、というやり方を解説している（次頁で図解）フラグメントキャッシュとはNextscape Inc. 199https://docs.microsoft.com/ja-jp/azure/api-management/api-management-sample-cache-by-key#fragment-caching色々できる柔軟性は素晴らしいが、そこまでAPI Managementで実装するのはやり過ぎではないだろうか・・・

• docs記載のシナリオを図解Nextscape Inc. 200フラグメントキャッシュとは1. Request API2. キー使ってキャッシュに顧客データがあるかを確認顧客データ航空予約システム4.予約データを取得3. キャッシュに顧客データがなかったら、外部からデータを取得し、キャッシュへ格納6. Response5.取得した予約データの一部のプレースホルダに対して、顧客データをセット顧客データを埋めるプレースホルダが予約データにある、という前提が現実的じゃない

フラグメントキャッシュとはNextscape Inc. 201• フラグメントキャッシュポリシーは３つのポリシーを使うキャッシュから値を取得するポリシー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

• 実装例（docsより）Nextscape Inc. 202フラグメントキャッシュとは<inbound><cache-lookup-valuekey="@("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”というキーでキャッシュから値を取得値がなかったらデータをキャッシュへ格納外部からデータを取得して変数に格納

Backup / RestoreBackup / Restore

Backup / RestoreコマンドAPI の Export / ImportGit の Repository を Clone3種類の Backup / RestoreがあるNextscape Inc. 204

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. 205REST APIを使うためにはAzrueADに設定が必要。かなり面倒なのでお勧めしない（PowerShellがいい）

Backup / Restore コマンドNextscape Inc. 206PS C:¥> # バックアップ先のStorageのContextを取得するPS C:¥> $storageContext = New-AzureStorageContext -StorageAccountName "ContosoStorage" -StorageAccountKey $storageKeyPS C:¥>PS C:¥> # バックアップ実行PS C:¥> Backup-AzureRmApiManagement `>> -ResourceGroupName "ContosoGroup02" `>> -Name "ContosoApi" `>> -StorageContext $storageContext `>> -TargetContainerName "ContosoBackups" `>> -TargetBlobName "ContosoBackup.apimbackup"PowerShell によるバックアップ（REST APIに比べて圧倒的に簡単！）• バックアップしてみるたった2つのコマンドだけ！

Backup / Restore コマンドNextscape Inc. 207PS C:¥> # バックアップ先のStorageのContextを取得するPS C:> $storageContext = New-AzureStorageContext -StorageAccountName "ContosoStorage" -StorageAccountKey $storageKeyPS C:¥>PS C:¥> # 復元実行PS C:> Restore-AzureRmApiManagement `>> -ResourceGroupName "ContosoGroup" `>> -Name "RestoredContosoApi" `>> -StorageContext $storageContext `>> -SourceContainerName "ContosoBackups" `>> -SourceBlobName "ContosoBackup.apimbackup"PowerShell による復元方法（こっちも２つのコマンドだけ。書き方ほぼ同じ）• Restore してみる• 復元先の API Managementインスタンスはあらかじめ作成しておくこと• Backup時と同じインスタンスレベル（Dev, Basic, Std, Premium）にすること• Restoreはめっちゃ時間かかる。15分～45分ぐらい

APIの設定に限定した Backup / Restore機能ImportでAPI のコピーが可能（違うAPIMインスタンスへのImportもOK）Azure Portal, REST API, Powershellコマンドのいずれかで実行可能バックアップデータはファイルダウンロードしてローカルに格納（Azure上に格納ではない）Importかなり早い（数秒）API の Export / ImportNextscape Inc. 208

Nextscape Inc. 209• Portalで API を ExportしてみるAPI の Export / Import

Nextscape Inc. 210• Export形式を選択するAPI の Export / Import

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,

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」

Nextscape Inc. 213• Blank APIテンプレートで APIを新規に作成するAPI の Export / Import• Display Nameに適当な値を入れる。どうせImportすると上書きされるので、なんでもOK• API URL suffix とは前頁の basePathのこと。他APIと重複しない値を設定する必要がある。（後から変更可能）

Nextscape Inc. 214• 今作ったAPI の Importをクリックし、Import形式を選ぶAPI の Export / Import

Nextscape Inc. 215• 「Select a file」でさっき修正したファイルを選ぶAPI の Export / Import

Nextscape Inc. 216• Import して APIがコピーされたAPI の Export / Import

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

API, Policy, 成果物、グループの設定情報がファイル形式（json）でAPIM内部の Git Repositoryに存在するGit へ Pushすると、 APIM のRepositoryからAPIMへDeployするらしい（WebAppsとそっくりな動作だ）同じインスタンスに対するBackup/ Restoreのみ？ユーザー、サブスクリプション、仮想ネットワークの接続設定はフjsonファイルに書き込まれていない（Restore されない）Git の Repository を Clone するNextscape Inc. 218

Nextscape Inc. 219• まず、Git へ APIM の情報を Commit するGit の Repository を Clone する

Nextscape Inc. 220• コミットされたGit の Repository を Clone する

Nextscape Inc. 221• Clone するためのアクセス資格情報を取得するGit の Repository を Clone する

Nextscape Inc. 222• Git Bash で Clone するとこんな感じ（普通の git cloneでしかない）Git の Repository を Clone する

Nextscape Inc. 223• Cloneした結果のWorkingTreeはこんな感じGit の Repository を Clone する

Nextscape Inc. 224• ローカルの Clone から、API Managementへ反映• ローカルから Push し、その後API Management へデプロイする（Push だけじゃ反映されないので注意！）Git の Repository を Clone するPushしてからデプロイ

Nextscape Inc. 225異なるAPI Management インスタンスへ Push&Deployできるのか実験Git の Repository を Clone するLoggerを全部削除すれば、できるのかも・・・。試していない• remote 先を異なる APIM にして git push --force で無理やりPush＆Deploy• Push 先の構成も git clone して、ローカルで置き換えてから Push&Deploy次の２つを試したがNGだった

Movatterモバイル変換

Change Language

Azure API Management 俺的マニュアル

Embed presentation

Recommended

More Related Content

What's hot

Similar to Azure API Management 俺的マニュアル

More from 貴志上坂

Azure API Management 俺的マニュアル

Editor's Notes

Movatterモバイル変換

Azure API Management 俺的マニュアル

Recommended

More Related Content

What's hot

Similar to Azure API Management 俺的マニュアル

More from 貴志 上坂

Azure API Management 俺的マニュアル

Editor's Notes

More from 貴志上坂