API 名
最終更新日 :
2022年1月19日
ColdFusion（2016 リリース）で導入された Adobe ColdFusion API Manager は、API の監視、測定、セキュリティ保護、マネタイズを提供するスタンドアロンサーバーコンポーネントです。API Manager は、REST または SOAP API を作成するためのテクノロジにとらわれないプラットフォームです。API Manager は、ASP.NET API にも、CFML ベースの API にも関係なく、クライアントからのリクエストをすべて実際のエンドポイント URL に送ります。
API Manager は、完全な機能を備えた管理ツールで、ColdFusion（2016 リリース）と統合されており、API のニーズに合わせた開発および管理プロセスのすべての要素が備わっています。 Adobe ColdFusion を使用すると、開発者は、REST と SOAP の両方の API をすばやく簡単に作成してデプロイできます。 API Manager では、システム管理者は、ロールベースのアクセス制御によって API もセキュリティで保護することができます。
API Manager の基本的な概念
役割とユーザー
API Manager は、次の役割をサポートします。
スロットルとレート制限
スロットルにより、期間内の API の使用を制御します。スロットルは、アプリケーションレベルおよび API レベルで定義できます。レート制限では、コンシューマーが API にアクセスできるレートを定義します。
詳しくはスロットルとレート制限を参照してください。API 管理者がスロットルとレート制限をどのように行うかについて詳しくは、SLA の設定を参照してください。
API 認証
API Manager で、API キーを使用して API およびアプリケーションを認証できます。API Manager は、API キーを生成し、API キーベースの認証を API に追加できるようにします。認証タイプには、次の 3 つがあります。
- apiKey
- basicAuth
- OAuth2
- None
詳しくは、API 認証タイプを参照してください。
アプリケーション
アプリケーションを作成して、アプリケーションにサブスクライブする API を取得します。詳しくは、アプリケーションの作成を参照してください。
API Manager のインストール
API Manager のインストーラーは、Adobe ColdFusion（2016 リリース）のエンタープライズ版のライセンスの一環として入手できます。ColdFusion をインストールするときに、API Manager をインストールするためのダイアログボックスが表示されます。API Manager をインストールした後、オペレーティングシステムによって、インストール後の手順が表示されます。
詳しくは、 API Manager のインストールを参照してください。インストール手順は、OS によって異なります。
インストール後、ブラウザーに「http://<localhost>:9000/portal.html」と入力して、API Manager ポータルを起動します。
API Manager を起動するときに問題が発生した場合は、トラブルシューティングのドキュメントを参照してから、API Manager を起動します。
REST API の作成
API の基本設定
初めて REST API を作成するには、API Manager ポータルにパブリッシャーとしてログインしてください。ログインすると、API を作成するための様々な方法がリストされた画面が表示されます。「REST API を作成」をクリックします。
例として、 米国 の特定の郵便番号を使用して、ある家の中央値を検索する API を作成することができます。この場合は、次の内容を確認する必要があります。
|
|
作成する API の名前。分かりやすい名前を入力します。この例では、「デモグラフィックス」と入力します。 |
|
コンテキスト |
API のコンテキストを定義するブラウザーフレンドリーな名前です。コンテキストは、API と同じように入力します。 |
|
バージョン |
API のバージョン。API には、複数のバージョンが含まれることがあります。API のバージョンに「v 1.0」と入力します。 |
|
エンドポイント |
この例では、Cdyne サービスプロバイダーによって公開されるサービスを使用できます。http://ws.cdyne.com/DemographixWS/DemographixQuery.asmx のエンドポイントを使用してください。 |
|
表示設定 |
この API をユーザーに公開する方法に応じて、公開、非公開、またはパートナーに設定します。 |
|
説明 |
API の説明を入力します。 |
API リソースの定義
この例では、リソース GetIncomeHouseValueByAddress が使用されています。GET メソッドをエンドポイントで使用します。「リソースパスを追加」フィールドに「/GetIncomeHouseValueByAddress 」と入力します。
エンドポイントには、次のパラメーターがあります。
- AddressLine1
- City
- StateAbbrev
- ZipCode
- LicenseKey
「リソース」セクションに以下のような情報を追加します。
|
1 |
GET メソッド |
|
2 |
リソース |
|
3 |
リソースのパラメーター。 |
API の認証
この例では、認証セクションの認証タイプで「なし」を選択します。
API の公開
API を公開するには、「公開」をクリックします。API が公開されると、API をプレビューできます。詳細を確認し、必要に応じて、API を編集して再度公開できます。
API のテスト
この API をテストするには、左側のナビゲーションパネルで「この API をテスト」をクリックします。リソースを展開します。次に示すように、パラメーターの値を入力します。
「API 呼び出しを実行」をクリックします。次のように表示されます。
API のサブスクライブ
パブリッシャーが API を作成して公開設楽、ユーザーはその API をサブスクライブできます。サブスクライバーとして API Manager ポータルにログインし、API カタログから API を選択します。
アプリケーションを購入し、SLA プランを選択します。また、API のテストに使用するアプリケーションキーを参照することもできます。
SOAP からの REST API の作成
基本設定
初めて REST API を作成するには、API Manager ポータルにパブリッシャーとしてログインしてください。ログインすると、API を作成するための様々な方法がリストされた画面が表示されます。「SOAP から REST API を作成」をクリックします。
例として、外部でアクセス可能な SOAP web サービスを使用して、REST エンドポイントを作成することができます。サンプル SOAP サービスの WSDL URL は http://wsf.cdyne.com/WeatherWS/Weather.asmx?wsdl です。
「基本設定」にすべてのフィールドを入力して「フェッチ」をクリックすると、SOAP to REST マッピングウィザードが表示されます。
SOAP to REST のマッピング
SOAP to REST ウィザードには、次のように表示されます。
「マッピング」には、次の3つの行があります。この例では、WeatherSoap を選択します。これは、SOAP バインディングがこの portType を使用しているためです。ポートのタイプを展開すると、ポートのタイプに関するメソッドが表示されます。
この実装は、portType に対してサポートされるバインディングを表します。この場合、SOAP 1.1 および SOAP 1.2 が存在し、WeatherSoapImpl（SOAP 1.1 バインディング）を選択しています。SOAP to REST API を公開する際、一度に複数のバインディングを選択することはできません。
REST パス（WeatherSoap）は、変換された REST サービスを利用できるようにするためのリソースのパスです。このフィールドは編集可能で、独自のリソースパス（REST パス）を定義できます。
SOAP to REST API メソッド
これで、個々の操作が REST にマッピングされるようになりました。次に示すように、メソッド getWeatherInformation を選択します。
このメソッドは、入力引数をとらず、情報を返します。「Produces」（Accept ヘッダー）を入力します。デフォルトでは、「Prorduces」に application/json と入力されます。コンマで区切られた複数の accept ヘッダーを適用できます。操作によって入力引数が実行されることはありません。そのため、「Consumes」（Content-type ヘッダー）が空になります。
タイプは、JAX-WS によって定義されているリソースメソッドを指定するものであり、同様の名前が付けられた HTTP メソッドに対応しています。GET、PUT、POST、DELETE は、SOAP to REST API 変換の有効なタイプです。
この操作については、デフォルト値の「GET」を指定します。
REST エンドポイントの生成
マッピング後に REST エンドポイントを作成するには、「REST エンドポイントの生成」をクリックします。REST サービスエンドポイントが作成され、ホストされるようになりました。ブラウザーに次の URL を入力すると、そのエンドポイントを呼び出すことができます。
http://localhost:9100/ WeatherSoapToRest/v1.0/WeatherSoap/ getCityWeatherByZIP/ “<cityZipCode>”
「リソース」セクションの API を確認します。
エンドポイント
この節では、入力 WSDL ドキュメントに生成された REST サービスについて、エンドポイント URL を確認できます。
現在の例では、Swagger ドキュメントは次の URL で使用できます。 http://localhost:9100/soaptoRest/WeatherSoapToRest/api-docs
URL は、リソースリストドキュメントへのリンクであり、このドキュメントから、次のように、API リストドキュメントの URL を取得できます。この例の場合は次のようになります。
http://localhost:9100/soaptoRest/WeatherSoapToRest/api-docs/WeatherSoap
Swagger ドキュメントについて詳しくは、Swagger 1.2 仕様を参照してください。
API のテスト
ポリシーに対して API をテストするには、左側のナビゲーションパネルで「この API をテスト」をクリックします。次の情報を入力し、「API 呼び出しを実行」をクリックします。
次のレスポンスが表示されます。
「要求の詳細」セクションには、この操作、HTTP メソッド、エンドポイントに送信された Accept ヘッダー、その他のヘッダーについてのリクエスト URL が表示されます。Params は送信された QueryParam です。この場合は apiKey= 808a92a6554c4b6b8fffabbf2e2d05f8 および arg0=10036 で、以下から呼び出すことができます。
http://localhost:9100/WeatherSoapToRest/v1.0/WeatherSoap/getCityWeatherByZIP?api_key= 808a92a6554c4b6b8fffabbf2e2d05f8&arg0=10036
次の結果が表示されます。
{"success":true,"responseText":"City Found","state":"NY","city":"New York","weatherStationCity":"White Plains","weatherID":15,"description":"N/A","temperature":"63","relativeHumidity":"87","wind":"E7","pressure":"29.97S","visibility":"","windChill":"","remarks":""}
Swagger からの REST API のインポート
Swagger は、API ドキュメントおよびサンドボックスを構築し、API クライアントのコードを生成するための仕様およびフレームワークです。
ColdFusion API Manager では、Swagger 仕様に基づく REST リソースをインポートおよび公開できます。
API Manager は、Swagger 1.2 および Swagger 2.0 からの API の読み込みをサポートしています。
基本設定
Swagger から REST API を読み込むには、「Swagger から REST API を読み込む」をクリックします。
この例では、Petstore API の Swagger ドキュメントを使用します。次の URL を入力します。
「読み込み」をクリックします。Swagger エンドポイント、バージョン、および説明がページに入力されていることを確認できます。API の名前とコンテキストを入力します。
参考資料
「リソース」セクションで、任意のリソースをクリックし、パラメーター、メソッド、認証タイプなどを表示します。
API の認証
この例では、 basicAuth 認証方式を使用します。
基本認証は、でユーザーを認証する最も簡単な方法です。 ユーザー名 とパスワード。API Manager では、基本認証スキームを使用して API を保護できます。パブリッシャーは、資格報の認証が必要なユーザーストアを設定する必要があります。API リソースがスコープによって保護され、ロールを使用して設定されている場合は、API の使用中にもロール認証が行われます。
次の例では、基本認証スキームを使用して、一般に公開されたペットストア API を認証する方法を手順に従って説明します。この例では、API Manager ゲートウェイ経由でバックエンドのユーザーストアとして LDAP ディレクトリを使用しています。
認証の種類を設定するには、次のようにします。
セキュリティ／認証に移動し、認証タイプとして basicAuth を選択します。「すべてのリソースに適用」をクリックします。これにより、すべてのリソースに対する認証方法として basicAuth が設定されます。また、この認証タイプをサブリソースレベルでも上書きすることができます。
「設定」ページで、認証情報が認証されるユーザーストアとして「ユーザーストア」を選択します。
Pet_write と pet_read の 2 つのスコープを作成します。ペットリーダーを使用しているユーザーだけがペットを読み取ることができます。ペットライターの役割を持つユーザーは、ペットを作成および削除することができます。
ペットリソースの GET 操作に使用するすべてのリソースに pet_read を割り当てます。「GET」以外のペットのすべてのリソースに、pet_write を割り当てます。
適切な SLA プランを選択し、API を公開します。
ColdFusion から REST API を読み込む
API Manager で、ColdFusion サーバーに登録されている REST サービスを読み込むこともできます。
次の例では、メッセージを表示する HelloWorld.cfc と呼ばれる CFC を作成します。ColdFusion ビルダーを使用して CFC を作成し、ファイルに以下の行を追加します。
<cfcomponent rest="true" restpath="/hello"> <cffunction name="sayHello" access="remote" returnType="string" httpMethod="GET"> <cfset myStr="こんにちは。REST アプリケーションです。"> <cfreturn myStr> </cffunction> </cfcomponent>
ColdFusion Administrator でサービスを登録します。
- サーバー設定／設定で「REST 確認を許可」を有効にします。
- ColdFusion Administrator で作成した CFC を登録します。
API Manager Administrator で ColdFusion サーバーを登録します。
CF ディスカバリサーバーウィンドウで、次の情報を入力します。
API Manager での REST API の読み込み
「ColdFusion から REST API を読み込む」をクリックすると、次のように表示されます。適切なサーバーを選択します。
「読み込み」をクリックします。この API に対して定義されているリソースがないので、リソースセクションにはリソースは表示されません。この API は、メッセージのみを返します。API を公開してテストします。次のように、メッセージが表示されます。
SOAP web サービスからの REST API の読み込み
ColdFusion API Manager では、SOAP web サービスを REST API として公開できます。「API を作成」ウィンドウで、「SOAP API の読み込み」をクリックします。
「 基本設定」ページで、次に示すように、API 情報と WSDL URL を入力します。
「フェッチ」をクリックします。API Manager は、WSDL を解析して、SOAP エンドポイント、ポートタイプ、操作などを識別します。また、すべてのエンドポイントと XSD ドキュメント参照が API Manager のランタイムゲートウェイを指すように書き換えられます。次を確認できます。
これでプロキシ WSDL が使用されていることを確認できます。このページには、使用可能なすべてのポートタイプ、メッセージエンベロープおよびエンドポイントが一覧表示されます。メッセージエンベロープも自動的に生成されます。エンベロープの近くにあるボタンをクリックすると、SOAP アクション、本文の種類、およびサンプルメッセージを示すダイアログボックスが表示されます。このサンプルは、API Manager によって生成されます。このサンプルでは、元の API のドキュメントが検証されています。
次の例は、ポートの種類が WeatherHttpGet、操作が GetCityWeatherByZIP の SOAP 1.2 メッセージエンベロープです。
「保存」をクリックすると、新しく作成されたプロキシサービスエンドポイントの概要が表示されます。
「公開」をクリックします
API の試用
API の公開後に「この API をテスト」をクリックすると、2つの WSDL URL が表示されます。最初の URL は元の WSDL URL、2 番目の URL は API Manager によって生成されるプロキシ URL です。
2つの WSDL を比較する場合は、実際のエンドポイント（http://wsf.cdyne.com/WeatherWS/Weather.asmx）が API Manager によって生成されたプロキシ（ http ://localhost:9100/WeatherWSDL/v1.0/{Binding}）に置き換えられます。
API を公開する前に、すべてのエンドポイント／XSD 参照が URL 「http://localhost:9100/WeatherWSDL/v1.0/」で始まることを確認してください。
サービス GetCityWeatherByZIP およびポートタイプ WeatherHttpGet をテストします。試行ウィンドウが表示されます。
郵便番号を入力して、「API 呼び出しを実行」をクリックします。「<ns1:ZIP>?xxx?</ns1:ZIP>」形式の有効な郵便番号を入力した場合は、次のようなメッセージが表示されます。
無効な郵便番号を入力した場合は、次のような応答が表示されます。
API Manager の Analytics
API Manager では、主要なメトリック、SLA の使用などを、一連のインタラクティブでグラフィカルなダッシュボードに記録することができます。API Manager ダッシュボードでは、次の操作を実行できます。
- API のパフォーマンスについて洞察を得る
- API の可用性と応答時間の監視
- API の使用状況の追跡
API Manager の Analytics ダッシュボードには、論理的に区切られた複数のダッシュボードが含まれています。例えば、パブリッシャーダッシュボードには次のパネルがあります。
- API リｒクエストの全体像を表示するホームパネル
- 異なる側面の API を比較するための API パネル
- 異なるバージョンの API を比較するための API とバージョンパネル
- API のエラー解析用のエラーパネル
- 開発者パネルは、サブスクライバーのリクエストとプランの追跡に使用できます。
各ダッシュボードには、複数のビジュアライゼーション（チャートやグラフ）が含まれています。ビジュアライゼーションには、円、ドーナツ、棒、線など、様々な形式があります。各ビジュアライゼーションでは、ユーザーが作成したフィールドに基づいて情報を提供します。フィールドは、API manager から収集された複数のデータのセットです。例えば、API 名、API バージョン、リクエストの種類、リクエストの応答時間などが挙げられます。
管理者とサブスクライバーには、それぞれ個別のダッシュボードがあります。詳しくは、次のリンクを参照してください。
- 管理者ダッシュボードに関するアドビのヘルプ記事。
- パブリッシャーダッシュボードに関するアドビのヘルプ記事。
- アドビシステムズ社のヘルプ記事（サブスクライバーダッシュボード）。
