19
Help us understand the problem. What are the problem?

More than 5 years have passed since last update.

posted at

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

Register as a new user and use Qiita more conveniently

  1. You can follow users and tags
  2. you can stock useful information
  3. You can make editorial suggestions for articles
What you can do with signing up
19
Help us understand the problem. What are the problem?