Apigee Edge で開発する

サービス プロバイダは、クライアント アプリが使用する API を開発します。API プロキシと API プロダクトを作成、構成、維持するには、以下で説明するように、Edge UI を使用するか、Apigee EdgeAPIs に HTTP リクエストを送信して RESTful サービスにアクセスします。

いずれの場合も、あらかじめ無料アカウントを作成しておく必要があります。作成方法については、Apigee アカウントを作成するをご覧ください。

Edge UI の使用

Edge UI は、API プロキシと API プロダクトの作成、構成、管理に使用できるブラウザベースのツールです。ただし、一部のタスクは API を使用する必要があります。

Edge UI の基本的な使い方については、最初の API プロキシを構築するをご覧ください。

次の URL にアクセスして Edge UI または従来の Edge UI にログインします。

Edge UI では次の操作を行うことができます。

  • コードを編集し、プロキシを通過するリクエスト フローをトレースすることで、API プロキシを作成する。
  • クライアント リクエストに公開するプロキシをまとめた API プロダクトを作成する。
  • デベロッパーとデベロッパー アプリを管理する。
  • テスト環境と本番環境を構成する。
  • JavaScript および Node.js アプリケーションを実装する。

次の図では、UI に API プロキシ エディタが表示されています。このエディタを使用して、API プロキシの作成と構成を行います。

Edge UI の API プロキシ エディタで [Develop] タブが選択されています。

Edge API の使用

Apigee Edge API を使用して、API プロキシと API プロダクト、API プロキシのロジックのポリシー、アプリとアプリ デベロッパー、キャッシュを作成、構成、管理できます。また API では、操作性を確保するために UI では表示されない低レベルの機能にもアクセスできます。

これらの API エンドポイントは、多くの場合、構成情報を含むデータを取得するので、これらのエンドポイントにアクセスするにはユーザー名、パスワードなどの認証情報を渡す必要があります。RESTful の原則に従うと、任意の API リソースで HTTP GET メソッド、POST メソッド、PUT メソッド、DELETE メソッドを呼び出すことができます。

他の RESTful API と同様に、Edge API は機能を API リソースとして公開しています。各リソースは、リソースに対してアクションを実行する一連のメソッドを定義します。

RESTful の原則に従うと、任意の API リソースで HTTP GET メソッド、POST メソッド、PUT メソッド、DELETE メソッドを呼び出すことができます。

  • GET: リソースのリスト、または特定リソースのプロファイルを取得します。
  • POST: リソースを作成します。または、パラメータで渡されたアクションをリソースに対して実行します。たとえば OAuth アクセス トークンを取り消すには、パラメータ action=revoke を使って POST メソッドを使用します。
  • PUT: 既存のリソースを更新します。
  • DELETE: 既存のリソースを削除します。

リソースと、リソースでサポートされているメソッドの完全なリストについては、Apigee 管理 API リファレンスをご覧ください。

アクセスの認証

API を呼び出すときには、API サーバーに対してユーザー自身を認証する必要があります。これは次のいずれかの方法で実行できます。

加えて、Agipee アカウントで 2 要素認証プロセスを有効化にするで説明しているように 2 要素認証プロセスを使用することが推奨されます。

ベースパスについて

API リクエストで使用するパスは、以下の内容を連結したものです。

  • 組織名を含むベースパス(組織名は、Edge UI の [User Settings] の下にあります)。
  • アクセスする Edge リソースを指すエンドポイント

たとえば、「apibuilders」という組織名の場合、API に対して実行する呼び出しでは、常に以下のベースパスを使用します。

https://api.enterprise.apigee.com/v1/organizations/apibuilders

組織に存在する API プロキシの一覧を取得するには、次に対する GET を呼び出します。

https://api.enterprise.apigee.com/v1/organizations/apibuilders/apis

多くのリソースでは、環境がスコープとなります。デフォルトでは test と prod の 2 つの環境が提供されています。たとえば、キャッシュのスコープは環境です。デフォルトでは、すべての環境に「mycache」という共有キャッシュが含まれています。

このキャッシュ リソースに対して GET を呼び出すと、次のようにキャッシュを一覧表示できます。

https://api.enterprise.apigee.com/v1/organizations/apibuilders/environments/test/caches
    https://api.enterprise.apigee.com/v1/organizations/apibuilders/environments/prod/caches

リクエスト URL の短縮

API のリクエスト URL を作成するときには、次の省略形を使用できます。

  • /e = /environments
  • /o = /organizations
  • /r = /revisions

省略形を使用する場合は、一貫した方法で使用する必要があります。上記の説明や次の例のように、省略する場合はパスのすべての要素を省略してください。パスの一部の要素だけを省略すると、エラーが発生します。

例:

    THIS:
    https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval/environments/prod/apis/helloworld/revisions/1/deployments
    CAN BE MUCH SHORTER:
    https://api.enterprise.apigee.com/v1/o/ahamilton-eval/e/prod/apis/helloworld/r/1/deployments

curl コマンドの実行

HTTP クライアントを使用して、API にリクエストを送信します。ドキュメントに記載されている多くの例では、幅広く使用されている HTTP クライアントである curl を使用した API リクエストがサンプルとして示されています。curl をインストールする必要がある場合は、http://curl.haxx.se からダウンロードできます。

Edge のサンプルを使用している場合は、ファイル /setup/setenv.sh の中で組織、ユーザー名、パスワードの値を設定します。いったん設定すると、簡素化されたデプロイを実行し、各サンプル API プロキシで提供されているスクリプトを呼び出すことができます。詳細については、サンプル API プロキシの使用をご覧ください。

API に対する呼び出しでは、レスポンスでの gzip 圧縮がサポートされています。API 呼び出しで 'Accept-Encoding: gzip, deflate' を設定すると、1024 バイトを超えるレスポンスはすべて gzip 形式で返されます。

XML および JSON のリクエストとレスポンスの形式設定

JSON はレスポンス メッセージのデフォルト形式です。XML が必要な場合は、JSON ではなく XML レスポンスを取得する目的で次の HTTP Accept ヘッダーを追加できます。

curl -H "Accept:text/xml" https://api.enterprise.apigee.com/v1/organizations/apifactory/apis -u email_address

ターミナルでの出力を見やすくするには、json.tool Python ライブラリなどの JSON 表現を使用してください。次に例を示します。

curl https://ahamilton-eval-test.apigee.net/getstarted -u email_address | python -m json.tool

XML では xmllint を使用できます。

curl https://ahamilton-eval-test.apigee.net/getstarted -u email_address | xmllint --format -

XML でペイロードを POST または PUT する場合は、Content-type HTTP ヘッダーを使用します。

acurl -H "Content-type:text/xml" -X POST -d \
    '<XMLPayload>
     </XMLPayload> ' \
    https://api.enterprise.apigee.com/v1/organizations/apifactory/apis -u email_address

デプロイ環境

Apigee Edge を使用しているすべての組織には、API の開発、テスト、デプロイに使用できる 2 種類の環境(「test」と「prod」)がデフォルトで用意されています。API を開発して公開前にテストするには「test」環境を使用します。社内のデベロッパーだけが、テスト環境にデプロイされている API にアクセスできます。アプリ デベロッパーに対して API を公開するには、API を「prod」環境にデプロイします。

デバッグとテスト

Edge API サービスには、エンドツーエンドのリクエストおよびレスポンス フローをデバッグできる Trace ツールが用意されています。トレースの結果には、リクエスト ヘッダー、レスポンス ヘッダー、ペイロード、ポリシーの実行、変数の値、およびフロー中に発生したすべてのエラーが表示されます。

トラブルシューティングで使用できる主要なデータポイント

  • タイムスタンプ: 各ステップの実行にかかる時間を確認するには、タイムスタンプを使用します。タイムスタンプを互いに比較すると、API 呼び出しを遅延させている、実行に最も時間がかかっているポリシーを特定できます。
  • ベースパス: ベースパスを検証することで、ポリシーによってメッセージが正しいサーバーにルーティングされていることを確認できます。
  • ポリシーの実行結果: ポリシーの実行結果では、メッセージが XML から JSON に変換されているかどうか、メッセージがキャッシュされているかどうかなど、メッセージが想定どおりに変更されることを確認できます。

次の図に、トレース結果を示します。

Edge UI の API プロキシ エディタで [Trace] タブが選択されています。

各トレース セッションは、次のステップに分かれています。

  • Original request received from client: クライアント アプリからのリクエストの動詞と URI パス、ヘッダー、本文データ、およびクエリ パラメータが表示されます。
  • Request sent to your backend service: API プロキシによってバックエンド サービスに送信されたリクエスト メッセージが表示されます。
  • Response returned by the backend service: バックエンド サービスによって返されたレスポンス ヘッダーとペイロードが表示されます。
  • Final response sent to client: レスポンス フローが実行された後に要求元のクライアント アプリに返されたレスポンス メッセージです。