Apigee Edgeの用語解説とポリシー機能一覧

はじめに

はじめまして、小西啓介です。

毎年この時期のAdvent Calendarを楽しみに読んでいましたが、今回、Advent CalendarはもちろんQiitaも初めてなので、温かい目で見守って下さい。

Tech-Circle Hands on Advent Calendar 2016
テーマ3: 3週目(11〜17) インフラ技術

さて、今週はインフラ技術ウィーク(あれ今日は18日？w)ということで、最近良く使っている
API GateWay製品の、Apigee Edge(以下 Edge)について書きます。
GoogleがApigee社を約600億円で買収したニュースをきっかけに日本でも改めてEdgeに注目される方が増えているので、少しでも情報提供できればと思います。

チュートリアル的なものが良いかなと思っていましたが、既にQiitaに分かりやすい記事を投稿さている方もいらっしゃるので、私は、Edgeの主要な用語解説とPolicy(EdgeでのAPI制御部品)について書きたいと思います。
基本的に私が、Edgeを勉強する中でのメモを元に書いていますので、認識に誤りなどがあればコメントをいただければ幸いです。

Edgeについて

まず、Edgeについて簡単に説明します。Edgeには様々な機能が備えられていますが、
APIトラフィックを扱う部分は、外部から見ると大きなReverseProxyになります。
そのReverseProxy内で、以下のような機能を実現しています。

• セキュリティ
• 流量制御
• ルーティング
• マッシュアップ
• トラフィックの変換・加工
• アナリティクス情報の収集

これらの機能を、大量のトラフィック（数千TPS等）でも処理出来るようにアーキテクチャーが設計されています。
内部は、いわゆるマイクロサービスのような形態で10以上のコンポーネントによって構成されており、コンポーネント毎にスケールアウト可能になっています。（コンポーネント間の接続はwebAPIに限らない）
また、高可用性・耐障害性が重視されていて、APIトラフィックを処理するコンポーネント以外が落ちてもAPIトラフィックを処理し続けるように設計されています。
実際に、EdgeのPublic Cloudについて、実績ベースで99.999%の可用性を誇っているそうです。(SLAは,複数リージョンで99.99%)

なお、Edgeには、開発者ポータルという、外部API利用者向けに、APIの仕様を開示したり
APIキーを発行等を行う機能や便利な（m）BaaS機能がライセンスには含まれていますが、Edgeのアーキテクチャーとは分離されたものとなります。(EdgeのManagement APIを利用し連携している)

主要な用語説明

それでは、用語説明です。

用語	解説
Organization(org)	Edgeの論理環境分離の単位となる。API Proxy、API Product、API Package、app、およびDeveloperを含むEdgeのすべてのオブジェクトを管理する単位となる。 例外として、Edgeの管理を行うuserについては、Organization単位でも管理を行うが、Global Admin userとすることで、複数のOrganization組織体に所属する事が出来る。
environment(env)	Edgeのデプロイ環境分離の単位となる。Trialでは、"prod"(本番)とtest"(テスト)の２環境がある。StartやProでは、"dev"を加えた3環境。
API	Edge内において多数の「API」という単語が出てくるが、Edgeの特定のオブジェクトを示す用語ではない。この為、厳密な定義は無いが、リソース(URI)とHTTPメソッド(verb)の組み合わせを示していることが多い。
API Proxy(proxy)	EdgeでのAPIの管理単位。複数のエンドポイントAPIの外部提供が可能。Edge管理画面やXMLセット、Edge管理APIで定義する。どのような単位でProxyを設定するか悩むところだが、Proxyを跨いでPolicy設定を共用することが出来ない為、Policyを共用したい単位で設定するべきである。
API Proxy Base Path	プロキシー単位にユニークな値を設定する。例："/Banking/v1/"
API product(product)	各API Proxyをグループ化し、このAPI product単位にアプリケーションに使用許可を割り当てる。このAPIプロダクトには、Scopeなどを設定できる
API package	マネタイズオプション(Monetization engine add-on)を導入した場合の料金プランに関連付けられているAPIプロダクトのコレクション
app(Developer App)	APIを利用するアプリケーションのこと、OAuthではクライアントと呼んでいるもの
flows	APIプロキシーは、各フローのパイプラインを通過することによってリクエストとレスポンスを管理する。リクエストとレスポンスのProxyEndpointとTargetEndpointにそれぞれPreFlow、Conditional flows、PostFlowの３つがある。(レスポンスのProxyEndpointにのみPostClientFlowがある(Message Logging Policy用))
Policy	APIの動作を制御するモジュールPolicy毎にXMLスキーマが定義されておりAPI Proxy内で設定を行ったPolicyを登録しフローに対して設定済みのPolicyを配置する。ポリシーにより設定できるフローに制限がある。セキュリティ、リクエストのレート制限、変換等がある。（詳細はポリシー機能一覧参照）
routes	プロキシーエンドポイントからターゲットエンドポイントへの接続の振分を行う。
ProxyEndpoint	APIプロキシで設定する外向きエンドポイントワイルドカード(*)が使用できる為、必ずしも、すべて指定する必要はない
TargetEndpoint	APIプロキシで設定する内向きエンドポイントターゲット無し(Null指定)や、Edge内のNodeをターゲットとすることが出来る。
Scope	OAuthでユーザ(ResouseOwner)からAPI利用者(Client)に対しての認可(委譲)同意する範囲の単位。基本的には、ユーザ(ResouseOwner)が何が出来るかを示すものでは無い。１項目だが、適切に使いこなすのは非常に難しい為、注意が必要(Scope自体はラベルでラベルを定義することは無いため、CSSのクラスと似ている)。Scopeが出てくるのは、基本的に４箇所。1. Admin UserがProductに、Clientに対して権限委譲依頼可能なScopeを設定2. ClientがAutherization Requestに1.のScopeの中でユーザに権限委譲依頼を行うScopeを設定3. ユーザが、認可同意画面でClientに対して2.のScopeの中で認可同意するScopeを選択しtoken発行4. Admin Userが、APIにOAuth2ポリシー(token validation)でリソースのアクセスなScopeを設定※Edge上で直接設定するのは、1.と4.だけである為、分かりにくいが1≧2≧3≧4となる必要がある。使用しない(常に空で利用する)ことも可能だが、空の指定＝全てのScopeを保持していることになる為、注意。特に存在しないscopeを指定した場合、エラーではなく削除される為、結果的に空となるケースについて意図しない動作とならないように注意。(空の場合にデフォルトのScopeを設定するよう実装するなどで対策する)
Conditions	API Proxyで動的にApigee Edgeの処理パイプラインを振り分けることが出来る。適用箇所は、ポリシーの適用、フローの実行、ルート。
API Keys(app keys)(Consumer keys)(Client Id)	app単位の割当だが、さらにProduct単位に異なるkeyを発行数ことも可能。API Key認証を行う場合のKey。OAuthで使用する場合はClient IDに相当する。Edge上は、API Key認証とOAuthでの利用は併用出来てしまうが、API key認証の場合はクレデンシャル情報になる為、絶対に共用しては行けない。(OAuthではClient IDは公開情報になる)Edge内でも呼び名が統一されていないことを公式に認めているので、注意。ランダムな文字列が割り当てられるが、UserAgentなどのリダイレクト中に参照出来る為、秘密情報ではない。ReGenerate Keyを行うと、Consumer Secretと共に、再生成される。
Consumer Secret(client secret)	OAuthの場合、Client IDに対するパスワード(のようなもの)ランダムな文字列が割り当てられる。
Developers	APIを利用する側の開発者のこと示す
Management UI	API Proxy、開発者、アプリケーション、ユーザ、カスタムレポートの登録・更新・削除。分析結果の参照等を行う。
Admin User	基本的には、Organization配下に存在するが、グローバルユーザとしてOrganizationを跨いだユーザとなる事が出来る。Private Cloudの場合、外部LDAPと連携する事が出来る。Permissions(Create/read/update/delete)やRolesの設定を行うことが出来る
Dashboard	ログイン直後のトップ画面、APIの稼働状況等のサマリがひと目で分かる。
Developer Engagement	ダッシュボードの１機能、開発者やアプリケーション単位にトラフィック量やエラーの量などを比較しながら表示することが出来る。
Callback URI	Oauthの認証認可の完了後等でUser Agentに遷移させる為の絶対URIOAuthのインプリシットフローでは、オープンリダイレクターになることを防ぐため、必ず登録させる必要がある。なお、クエリーパラメータの付与については、許容しているため、UserAgent側で持ち回す情報を設定することも出来る。
Developer Portal	開発者への情報提供・コミュニケーション、管理ツールCRMのDrupal(OSS)上にApigeeが提供するモジュールを導入することで構築する。Apigee EdgeのManagement APIを呼び出して連携している。Drupalに構築するものとは別に、新しくEdge組み込まれた簡易的なDeveloper Portalがβリリース(2016/12現在)されている。Swaggerとの親和性が高くなり、MarkDown形式でコンテンツを記載できるなど注目点が多い。
version	API Proxyのベースパス等に指定する"/v1/"のバージョンのことApigee Edegeで管理対象ではない。
revision	API Proxyの変更管理単位。Org単位に管理されている。API Proxyへの変更をSaveする際にリビジョンを上げるか選択出来る。(上げないと変更が正しく反映出来ない場合もある為、上げるように指示が合った場合は素直に上げること)env毎にどのrevisionをデプロイするか選択できため、テストしてからリリースということが簡単に出来る。また、特定のenvにしかデプロイしないことでテスト専用のProxyを作成することも可能例："prod"env => rev.5"test"env => rev.4
Caching	レスポンスの高速化やバックエンドの保護を目的としてApigee上でキャッシュを利用する事が出来る。様々な単位（ユーザ共通やユーザ単位等）でキャッシュのキーを設定することが出来る。メッセージプロセッサー上のL1キャシュと、Cassandra上のL2キャッシュがある
Public Cloud	Apigeeの管理下であるインフラで製品を利用する場合の導入形態ライセンスには、インフラ構築費用と運用費用が含まれている。
Private Cloud(On Premise)	Apigeeの管理下でないインフラ（自分で管理しているAWS等を含む）で製品を利用する場合の導入形態ライセンスには、インフラ構築費用と運用費用が含まれていない。以前は、オンプレミスと呼んでいたが、"On Premise"から"Private Cloud"に名称変更している為、"Private Cloud"の利用を推奨。(理由について、想像だが、物理サーバだけでなく、IaaS等への導入が増えているためと思われる)

ポリシー一覧

ポリシーは、Management UIの設定画面では名前は自分で割り当てたものである為、何のポリシーかアイコンで見分ける場合もある為、アイコンを覚えておいた方が便利です。ただし、アイコンは複数のポリシーで共通の場合もあるので注意。

X	機能分類	分類説明	ポリシーグループ	アイコン	ポリシー名	Apigee doc Link	XML Element	概要	詳細	備考
1	トラフィック管理	同時レート制限や、制御トラフィックのクォータとスパイク、およびキャッシュ等の設定を行う	Cache policies		Response Cache	★	ResponseCache	レスポンスのキャッシュ
2	(Traffic management policies)	↑	↑		Populate Cache	★	PopulateCache	キャッシュの追加
3	↑	↑	↑		Lookup Cache	★	LookupCache	キャッシュの参照
4	↑	↑	↑		Invalidate Cache	★	InvalidateCache	キャッシュの無効化
5	↑	↑	Concurrent Rate Limit policy		Concurrent Rate Limit	★	ConcurrentRatelimit	同時接続数制限	キャッシュアクセスを除く実際にバックエンドへの同時接続数を制限する	MessageProcessor単位に同時接続数を保有する
6	↑	↑	Quota policy		Quota	★	Quota	接続数割当	特定の期間での特定の対象からのバックエンド接続を制限する	基本的には、ProxyEndpoint Request PreFlowのユーザ認証後に実装する
7	↑	↑	Reset Quota policy		Reset Quota	★	ResetQuota	接続数割当リセット	特定の期間での特定の対象からのバックエンド接続を制限する
8	↑	↑	Spike Arrest policy		Spike Arrest	★	SpikeArrest	スパイク阻止	深刻なトラフィックの急増からバックエンドを保護する
9	仲介機能	メッセージの構文解析、変換、ならびに検証、およびエラー処理の実行を行う	Access Entity policy		Access Entity	★	AccessEntity	エンティティアクセス	App,API product,Consumer key,Developer等のエンティティ情報を取得する
10	(Mediation policies)	↑	Assign Message policy		Assign Message	★	AssignMessage	メッセージ割当	リクエスト及びレスポンスのメッセージの作成または変更を行う	様々な用途に使用される
11	↑	↑	Extract Variables policy		Extract Variables	★	ExtractVariables	変数抽出	リクエスト又はレスポンスのヘッダー、URI、ペイロード、フォームパラメータ、及びクエリパラメータから抽出可能
12	↑	↑	Key Value Map Operations policy		Key Value Map Operations	★	KeyValueMapOperations	キーバリューマップ操作	Proxyの設定情報を外部化したり、
13	↑	↑	Raise Fault policy		Raise Fault	★	RaiseFault	例外処理	通常、Policy上でエラーが発生した場合やバックエンドからのレスポンスコードなどによって例外処理が行われるが、このポリシーによって、任意の条件等で強制的に例外処理に流すことが出来ます。
14	↑	↑	SOAP Message Validation policy		SOAP Message Validation	★	MessageValidation	SOAPメッセージ精査	WSDLをインポートした場合、このポリシーが自動的に設定される	現時点では、これのSwagger版は無い為、内蔵Node等で対応する必要がある。
15	↑	↑	XML to JSON policy		XML to JSON	★	XMLToJSON	XMLをJSONに変換
16	↑	↑	JSON to XML policy		JSON to XML	★	JSONToXML	JSONをXMLに変換
17	↑	↑	XSL Transform policy		XSL Transform	★	XSL	XMLをXSLTを使用してフォーマット変換		JSONに対しては、Javascriptポリシーを使用してフォーマット変換を行う。
18	セキュリティ機能	OAuth、APIキーの検証、およびその他の脅威からの保護機能を使用してAPIへのアクセスを制御する	Access Control policy		Access Control	★	AccessControl	IPアドレス制限
19	(Security policies)	↑	Basic Authentication policy		Basic Authentication	★	BasicAuthentication	ベーシック認証	外部からのBasic認証及び外部へのBasic認証を行う際に、BASE64の文字列のデコード、エンコードを行う。外部からのBasic認証を行う場合は、Raise FaultやKey Value Mapを使って実装する必要がある。	このPolicy自体がBasic認証を行ってくれる訳ではないので注意。
20	↑	↑	JSON Threat Protection policy		JSON Threat Protection	★	JSONThreatProtection	JSON脅威防止	無限にネストしたJSONなどに対してバックエンドを保護する
21	↑	↑	XML Threat Protection policy		XML Threat Protection	★	XMLThreatProtection	XML脅威防止	無限にネストしたXMLなどに対してバックエンドを保護する
22	↑	↑	Regular Expression Protection policy		Regular Expression Protection	★	RegularExpressionProtection	正規表現防止	このポリシーを用いてSQLインジェクション対策などを行う
23	↑	↑	Verify API Key policy		Verify API Key	★	VerifyAPIKey	APIキー検証	APIキーでの認証時だけでなくOAuth(ClientID)でも使用可能
24	↑	↑	OAuth v2.0 policies		OAuth v2.0	★	OAuthV2	OAuth2.0全般	アクセストークン検証、アクセストークン生成、認証コード生成、トークンリフレッシュ等の実施 ※Operationタグに設定する内容により異なる動作となる。 GenerateAccessToken GenerateAccessTokenImplicitGrant GenerateAuthorizationCode RefreshAccessToken VerifyAccessToken InvalidateToken ValidateToken	現時点では、このポリシーに対するXML Schemaは提供されていない。
25	↑	↑	↑		Get OAuth v2.0 Info	★	GetOAuthV2Info	OAuth2.0属性情報取得	アクセストークン、リフレッシュトークン、認証コード等に紐づく属性情報の取得
26	↑	↑	↑		Set OAuth v2.0 Info	★	SetOAuthV2Info	OAuth2.0属性情報設定	アクセストークン、リフレッシュトークン、認証コード等に紐づく属性情報の設定
27	↑	↑	↑		Delete OAuth v2.0 Info	★	DeleteOAuthV2Info	OAuth2.0属性情報削除	アクセストークン、リフレッシュトークン、認証コード等に紐づく属性情報の削除
28	↑	↑	OAuth v1.0a policies		OAuth v1.0a	★	OAuthV1
29	↑	↑	↑		Get OAuth v1.0a Info	★	GetOAuthV1Info
30	↑	↑	↑		Delete OAuth v1.0 Info	★	DeleteOAuthV1Info
31	↑	↑	SAML Assertion policies		Generate SAML Assertion	★	GenerateSAMLAssertion
32	↑	↑	↑		Validate SAML Assertion	★	GenerateSAMLAssertion
33	↑	↑	LDAP policy **		LDAP	★	Ldap	LDAP		** PrivateCloud　Only
34	拡張機能	サービスコールアウト、メッセージデータの収集、およびJava、JavaScript、およびPythonのコードの呼出等のカスタムポリシー機能を提供する	Message Logging policy		Message Logging	★	MessageLogging	メッセージロギング	外部にsyslog形式等でトラフィックの情報を転送できます。パフォーマンスに影響を与えないよう、Clientにレスポンスを返した後のフローに配置することが出来ます。
35	(Extension policies)	↑	Service Callout policy		Service Callout	★	LocalTargetConnection	サービスコールアウト	フロー中に内部・外部のAPIを呼び出しを行うことが出来る。
36	↑	↑	Statistics Collector policy		Statistics Collector	★	StatisticsCollector	統計情報収集	監視の為だけではなく、Google Analyticsのようなビジネス判断に役立てる情報を収集します。統計情報の収集はパフォーマンスに影響を与えないようキューイング処理され、非同期で格納が行われます。
37	↑	↑	JavaScript policy		JavaScript	★	Javascript	JavaScriptカスタム	JavaScriptのリソースファイルをフロー中に呼び出すことにより、リクエストやレスポンスの変数を書き換える事が可能。ライブラリの取り込みも可能。	JSONPathライブラリによるリマッピングが可能
38	↑	↑	Java Callout policy *		Java Callout	★	JavaCallout			* Enterprise　Only
39	↑	↑	Python Script policy *		Python	★	Script			* Enterprise　Only