Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Apigee API コンソールの設定

The legacy API Console is a free hosted service that is separate from Apigee Edge with no service-level agreement (SLA) guarantee.

API プロキシを作成および展開することで、新しい API を作成します。API は、環境に展開されるすべての API プロキシによって公開されます。API は、既存のサービスのファサードになる場合や、 JavaScript または Node.js アプリケーションを公開するだけの場合があります。

これらの API を検出、理解、使用する方法をデベロッパに提供する必要があります。この場合、一般的に理解されている方法で、API を記述するファイルを作成します。サービスの記述に利用可能な言語は数種類あります。API の場合は、一般に Web アプリケーション記述言語 (WADL) を使用します。

WADL の詳細については、World Wide Web Consortium (W3C) の Web サイトの WADL 仕様 (http://www.w3.org/Submission/wadl/) を参照してください。

WADL は、人と機械の両方が読み取り可能なインターフェイスの構造を体系化した仕様 (標準ではありません) です。API を記述するための最適な方法については、当然多くの議論があります。Apigee では、インターフェイスを記述するための (制限はありますが) 便利なツールとして WADL を扱いますが、WADL を推奨しているわけではありません。

アプリケーションコードから WADL ファイルを生成する場合、多くのルールを利用できますが、WADL ファイルは手作業でも無理なく作成できます。WADL ファイルは XML ファイルで、一般に .xml 拡張子が使用されます。

API はすべて単一の WADL を使用して記述します。作成した WADL ファイルは、Apigee API Console To-Go を使用してデベロッパに公開できます。この場合は、Console To-Go Web ページで Web フォームを使用して、ファイルを Apigee にアップロードします。API のモデル化と同様、Console の作成も対話型プロセスです。カスタム Console の外観をカスタマイズすることもできます。作成したカスタム Console に問題ない場合は、各自の Web サイトまたは Developer Services ポータルのいずれかに展開できます。

WADL とは

Web アプリケーション記述言語 (WADL) は、HTTP ベースの Web API の記述を機械で読み取り可能にする XML ベースのファイル形式です。WADL ファイルでは、API を構成するリソース (URI) を定義します。WADL では、リソースごとに、これらのリソース上で動作する 1 つ以上のメソッドを定義します。RESTful API では、メソッドはリソース (URI) と、リソースで動作する HTTP 動詞 (一般的には GET、PUT、POST および DELETE) を組み合わせたものになります。WADL の最も簡単な形式では、API で定義されたリソースでの作成、読み取り、更新および削除のアクション (CRUD 操作とも呼ばれます) を定義します。

例えば、記事、コメント、ユーザーの 3 つのリソースを定義する API があるとします。

  • http://api.example.com/v1/articles
  • http://api.example.com/v1/comments
  • http://api.example.com/v1/users

デベロッパは、リソースの作成、読み取り、更新、削除の方法、すなわち各リソースに必要な一連のメソッドが API リソースごとに必要です。

RESTful API では、一般に次のメソッドが定義されます。

  • POST メソッド (記事を作成)
  • PUT メソッド (既存の維持を変更)
  • GET メソッド (記事を取得)
  • DELETE メソッド (記事を削除)

定義したメソッドには、パラメータを指定できます。パラメータにより、リソースの操作をきめ細かく制御できます。WADL のパラメータを操作するさまざまな方法があります。この例では、パラメータは一般にクエリーパラメータの形式になります。

  • http://api.example.com/v1/articles?topic=programming

Apigee Console を使用するメリットの 1 つは、API でサポートされるパラメータと、特定のタスクを達成するためにパラメータをどのように使用できるかについて、デベロッパがすぐに理解できることです。

この API のリソースとメソッドに WADL をそれぞれ定義してみましょう。WADL では、次のように定義します。

  • API のベースパス
  • /articles URI パスで定義される単一のリソース
  • /article リソースの単一の GET メソッド。このメソッドはすべての記事のリストを返します。
  • GET メソッドの単一のクエリーパラメータ (トピック)。すべての記事をトピック別にフィルタできます。
<resources base="http://api.example.com/v1">
    <resource path="articles">
        <method id="listArticles" name="GET">
             <request>
                 <param name="topic" required="true" 
                     type="xsd:string" style="query" default=""/>
             </request>
        </method>
     </resource>
</resources>

次に、前述の WADL を Apigee Console で表示可能な WADL に変えてみましょう。 WADL は <application> タグでラップされ、myExampleWADL.xml ファイルに書き込まれます。

<application xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema"
             xmlns:apigee="http://api.apigee.com/wadl/2010/07/"
             xmlns="http://wadl.dev.java.net/2009/02"
             xsi:schemaLocation="http://wadl.dev.java.net/2009/02 
                 http://apigee.com/schemas/wadl-schema.xsd 
                 http://api.apigee.com/wadl/2010/07/ 
                 http://apigee.com/schemas/apigee-wadl-extensions.xsd">
    <resources base="http://api.example.com/v1">
        <resource path="articles">       
            <method id="listArticles" name="GET" apigee:displayName="List Articles">
                <apigee:tags>
                    <apigee:tag primary="true">Articles</apigee:tag>
                </apigee:tags>
                <apigee:authentication required="true"/>
                <doc apigee:url="http://doc.example.com/apis/listArticles.html">
                    Use the GET method to list all articles, filtered by 'topic'
                </doc>
                <request>
                   <param name="topic" required="true" 
                       type="xsd:string" style="query" default=""/>
                </request>
            </method>
        </resource>
    </resources>
</application>

Apigee では WADL 標準がどのように拡張されるか

Apigee では、Apigee 固有の要素で基本的な WADL 仕様を拡張します。これらの拡張により、Console 内の API の表示を制御できるだけでなく、API に関する追加のドキュメントで Console を強化することもできます。

Apigee では、次の WADL 拡張を定義します。

  • 認証: <apigee:authentication> タグでは、認証に必要な API メソッドを示します。
  • タグ: <apigee:tags> および <apigee:tags> タグでは、Console で関連する API メソッドをカテゴリにグループ化できるようにする API メソッドの識別子を指定します。
  • 選択肢: <apigee:choice> タグでは、Console によってユーザーに表示されるパラメータのセットの選択肢を定義できます。
  • 表示名: <method> タグの apigee:displayName 属性では、Console でユーザーに表示される API メソッドのわかりやすい名前を指定します。
  • ペイロード: <request> タグの <apigee:payload> 子タグでは、Console でユーザーに表示され、リクエストメッセージの一部として API に送信される JSON または XML リクエスト本文 (多くの場合 POST または PUT 操作に使用) を指定します。
  • 添付ファイル: <request> タグの <apigee:attachments> 子タグでは、MIME エンコードされた添付ファイルとしてリクエストメッセージに含めるファイル (イメージ、音声ファイル、ビデオファイル) を Console ユーザーが選択できます。
  • Doc URL: <doc> タグの apigee:url 属性では、各自でホストした Web ページのリンク、API メソッドに関する詳細情報を提供する API プロバイダを指定します。

これらの拡張の中で必要なのは、認証とタグの 2 つのみです。WADL が Console で機能するには、WADL で定義されたすべての API メソッドに、認証およびタグの要素を追加する必要があります。それ以外の拡張は省略可能で、Console ユーザーの API のユーザーエクスペリエンスを改善する必要がある場合に使用できます。

Apigee 固有のタグの先頭には、キー名 apigee (<apigee:tags><apigee:authentication> など) が付きます。

(Apigee 固有の WADL 拡張の詳細については、「WADL リファレンス」の「Apigee WADL 拡張の概要」を参照してください。)

Apigee コンソールの WADL の作成

Apigee Console で使用する WADL を作成する場合は、2 つの戦略があります。

戦略 1: Apigee から提供されているサンプルの WADL ファイルをダウンロードします。これは、API を記述するための開始点として使用します。次に、API メソッドの 1 つまたは 2 つに WADL エントリを作成し、Apigee Console にアップロードします。これらのメソッドが問題なく機能することを確認し、残りの API メソッドを WADL ファイルに追加していきます。サンプルの WADL は、こちらからダウンロードするか、Apigee Console To-Go Web ページの右側のリンクを使用してください。詳細については、Apigee WADL スキーマ (こちら) を参照してください。 

戦略 2: オープンソースの Jersey 自動 XML スキーマジェネレータなどのツールを使用して、 WADL を作成します。 Console で機能するには、必要な Apigee WADL 拡張、認証およびタグを WADL に追加します。ドキュメント URL などのその他の拡張は省略可能で、必要に応じて追加できます。 

「WADL リファレンス」では、WADL 表現について説明しています。この記事の「WADL の要素」では、各種要素が Apigee Console にどのように表示されるかについて示されています。 「WADL リファレンス」の「Apigee WADL 拡張の概要」には、 Apigee 固有の拡張がまとめられています。

Apigee Console To-Go の作成と WADL ファイルのアップロード

Apigee Console To-Go を作成するには、https://enterprise.apigee.com でアカウントが必要です。Console To-Go は、デベロッパであれば、だれでも作成できます。

一般には単一のコンソールをポータルに作成しますが、Apigee では、デベロッパアカウントごとに 最大 10 の Consoles To-Go を作成できます。上限に達すると、アラートが表示されます。

Console To-Go では、アクセスは制限されないため、作成した Console To-Go にはだれでもアクセスできますが、API にアクセス資格情報を適用できます。これにより、だれでもコンソールを参照できるようにする一方、必要な資格情報を持ったユーザーのみが要求できるように設定できます。

Console To-Go の作成プロセスは、次の 3 つの手順で定義されます。

  1. 設定 - 必須の手順です。この手順では、Console To-Go の名前と URL、API のアクセスに必要な資格情報を指定し、WADL ファイルをアップロードします。
  2. スタイル - (省略可能) Console To-Go の外観を制御するスタイルを設定します。
  3. 埋め込み - (省略可能) <iframe> タグをコピーします。このタグにより、Console To-Go を別のページに埋め込むことができます。

手順 2 と 3 は省略可能です。Console To-Go の作成と WADL ファイルのアップロードは、手順 1 を実行するだけで可能です。手順 2 と 3 は、Console To-Go を作成する場合に、必要に応じて実行できます。これらの手順は、戻って後で実行することもできます。 

コンソールを設定して WADL ファイルをアップロードするには、次の手順に従います。

  1. Apigee アカウントを https://enterprise.apigee.com で作成します (無料のアカウントを https://accounts.apigee.com/accounts/sign_up で取得できます)。
  2. https://apigee.com/togo の URL を開きます。「Console-To-Go」ページが開き、「Step 1 - Set up」が表示されます。


     
  3. Console の名前と URL を指定します。
  4. コンソールを保存します。
  5. ページを下にスクロールし、Console To-Go のアクセスに必要な資格情報を選択します。
  6. 「Save Credentials」を選択します。
  7. ページを下にスクロールし、WADL ファイルをアップロードします。
  8. 「Browse」ボタンを選択して WADL ファイルに移動し、「Open」を選択します。
  9. 「Upload」ボタンを選択します。
     Console To-Go が WADL ファイルでエラーを検出すると、エラーメッセージが表示されます。
  10. 手順 8 と 9 を繰り返し、WADL ファイルをアップロードします。 すべての API を単一の WADL ファイルに記述する必要があります。
    Console To-Go を作成したら、初期 WADL ファイルをアップロードし、https://apigee.com/togo に戻り、いつでも WADL ファイルをアップロードできます。

コンソールのスタイルを設定するには、次の手順に従います。

  1. 前述の Console To-Go をすでに作成していることを確認します。
  2. https://apigee.com/togo の URL を開きます。
  3. 既存のコンソールの名前と URL を指定します。
  4. ページの上部の「2. Style」を選択します。
  5. Console To-Go のスタイルを編集し、「Save Changes」を選択します。

コンソールを個別のページに埋め込むには、次の手順に従います。

  1. 前述の Console To-Go をすでに作成していることを確認します。
  2. https://apigee.com/togo の URL を開きます。
  3. 既存のコンソールの名前と URL を指定します。
  4. ページの上部の「3. Embed」を選択します。
  5. ページから埋め込み先のページに <iframe> タグをコピーします。

Apigee API Console To-Go の展開

Apigee API コンソールを作成して WADL ファイルをアップロードすると、展開用の複数のオプションが表示されます。

オプション 1: 各自の Web サイトまたはデベロッパポータルに作成するカスタムコンソールを埋め込みます。Apigee API コンソールの作成プロセスの一部として、Apigee により、コンソールに埋め込み可能な HTML <iframe> タグが生成されます。<iframe> タグにより、Web ページ上で埋め込んだ場所にコンソールがレンダリングされます。

オプション 2: URL をコンソールに配信し、デベロッパが直接アクセスできるようにします。例えば、ポータルの最上部のメニューバーに、コンソールのリンクを追加できます。

オプション 3: コンソールが Apigee プロバイダページに含まれるようにします。このオプションはコストがかからず、API の視認性が向上し、新たなデベロッパを API に呼び込むことができます。Apigee サイトにコンソールを表示する方法の詳細については、Apigee (consoles@apigee.com) にお問い合わせください。

Console To-Go の更新

コンソールを変更する必要がある場合は、WADL を更新して、以前の WADL に対して再度アップロードします。

  1. WADL を更新します。既存の WADL を常に取得できるようにするには、「Set Up」タブ (https://apigee.com/togo) からダウンロードします。


     
  2. 新しい WADL をアップロードする準備ができたら、「Set Up」タブ (https://apigee.com/togo) に移動します。
  3. ページの「Upload WADL」セクションで、「Choose File」をクリックして WADL を選択します。
  4. (省略可能) WADL ファイルを選択した後に「Preview WADL in Console」をクリックすると、プレビューできます。
  5. 「Upload」をクリックします。コンソールが更新されます。

 

Help or comments?