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.

管理 API を使用した API プロキシの展開

どの組織にも独自のソフトウェア開発ライフサイクル (SDLC) があるものです。多くの場合、API プロキシの展開は、バックエンドサービスで用いられているプロセスに合わせて行うことが必要となります。

このトピックで取り上げられている Edge 管理 API メソッドは、API プロキシ管理を 自組織の SDLC に統合するために使用できます。 この API の一般的な用途は、他のアプリケーションの展開や移行も伴うより大掛かりな自動処理の一環として、API プロキシを展開したり API プロキシを環境 (environment) 間で移行したりするスクリプトやコードを作成することです。

管理 API は、組織の SDLC を (そしていかなる類いの SDLC も) 想定しません。逆に、展開担当チームが API 展開ライフサイクルを自動化および最適化するために調整できるアトミック関数が公開されています。

管理 API については「APIs」にすべて記載されています。このトピックでは、API プロキシを管理するための API に注目します。

ビデオ: API の展開方法について、この短いビデオをご覧ください。

API とのやり取り

ここからは、API とのシンプルなやり取りについて順を追って見ていきます。

組織内の API のリスト

手始めに、組織の API プロキシをすべてリストします (エントリ email:password および {org_name} を忘れずに置き換えてください。手順については、「API reference getting started」を参照してください。

$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/apis

サンプルレスポンス:

[ "weatherapi" ]

API の取得

組織に存在する任意の API プロキシに対して GET メソッドを呼び出せます。呼び出すと、API プロキシの利用可能な全リビジョンのリストが返されます。

$ curl -u email:password -H "Accept: application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis/weatherapi

サンプルレスポンス:

{
  "name" : "weatherapi",
  "revision" : [ "1" ]
}

このメソッドから返される詳細は、API プロキシの名前と、関連付けられている「リビジョン」だけです。リビジョンには数値が関連付けられています。API プロキシは、構成ファイルのバンドルから成っています。リビジョンは、イテレーションに伴う構成の更新を管理するための軽量メカニズムです。リビジョンは連番形式で、API プロキシの以前のリビジョンを展開すれば変更を元に戻せます。また、API プロキシのあるリビジョンを prod 環境に展開しつつ、その API プロキシの新たなリビジョンの作成を test 環境で継続することもできます。用意が整ったら、リビジョンの高いほうの API プロキシを test 環境から「昇格」させて、prod 環境にある以前のリビジョンを上書きできます。

この例の場合、API プロキシは作成されたばかりで、リビジョンは 1 つしかありません。API プロキシが構成と展開のイテレーションを経るにつれて、リビジョン番号が整数単位で大きくなります。任意で、API を直接呼び出して展開することで、API プロキシのリビジョン番号を上げることができます。若干の変更の場合は、リビジョンを上げないことも考えられます。

API リビジョンの取得

API (つまり公開されているインターフェイス) のバージョンと API プロキシのリビジョン (構成に関連付けられている内部的な番号) はしっかり区別してください。この 2 つの数値に関連はなく、API を使用するアプリに API プロキシのリビジョン番号のことはまったくわかりません。

API のバージョン (api.company.com/v1 など) は、あまり頻繁に変更しないようにしてください。API のバージョンを上げることは、API によって公開されている外部インターフェイスのシグネチャーに大きな変更があったとデベロッパに通知することに相当します。

The API proxy revision is an incremented number associated with an API proxy configuration. API Services maintains revisions of your configurations so that you can revert a configuration when something goes wrong. By default, an API proxy's revision is automatically incremented every time you import an API proxy by using the Import a new API Proxy API. If you don't want to increment an API proxy's revision, use the Update API Proxy Revision API. If you're using Maven to deploy, use the clean or update options, as described in the Maven plugin readme.

API プロキシ構成の詳しいプロファイルを取得するには、特定のリビジョン番号に対して GET メソッドを呼び出します。

例えば、API プロキシリビジョン 1 の GET メソッドを呼び出して詳細表示を取得できます。

$ curl -u email:password -H "Accept:application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis/weatherapi/revisions/1

サンプルレスポンス

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1343178905169,
  "createdBy" : "andrew@apigee.com",
  "lastModifiedAt" : 1343178905169,
  "lastModifiedBy" : "andrew@apigee.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

これらの API プロキシ構成要素については、「API proxy configuration reference」に詳しい記載があります。

環境への API の展開

リクエストを受信したり転送したりするように構成された API プロキシは、1 つまたは複数の環境に展開できます。通常、API プロキシは「test」でイテレーション作成され、用意が整うと、その API プロキシリビジョンを「prod」に「昇格」させます。 往々にして、API プロキシのリビジョンは test 環境のほうが多くなります。prod 環境でイテレーションを実施することがほとんどないからです。

API プロキシは、環境に展開されて初めて呼び出せるようになります。API プロキシリビジョンを prod に展開したら、その「prod」の URL を外部デベロッパに公開できます。

ここまで見てきたように、環境には API リビジョンを展開するので、API プロキシリビジョン展開における第 1 歩は、組織内の環境のリストを検証することとなります。

環境のリスト手順

Apigee Edge のどの組織にも、環境として少なくとも「test」と「prod」の 2 つがあります。この名前の付け方は任意です。目的は、API プロキシが適切に動作することを外部デベロッパに公開する前に検証するための領域を提供することです。 

各環境は実は単なるネットワークアドレスであり、作業対象の API プロキシ間や実行時にアプリからアクセスされる API プロキシ間のトラフィックを分離します。

環境は、データとリソースも分離します。例えば、test と prod でキャッシュを別個にセットアップして、該当環境で実行されている API プロキシにしかアクセスできないようにできます。

組織に存在する環境の表示

$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/environments

サンプルレスポンス

[ "test", "prod" ]
Apigee Edge をオンプレミス環境にインストールしている場合は、表示される環境のリストがこれとは異なることがあります。

展開の調査

「展開」とは、環境に展開された API プロキシのリビジョンです。「展開済み」状態にある API プロキシには、ネットワーク経由で、その環境の VirtualHost に定義されたアドレスでアクセスできます。

API が展開されている環境 (や、そもそも展開されているかどうか!) をときどきチェックすることをお勧めします。 例えば、API プロキシへのリクエストが失敗しているのに気づくことがあります。その場合、トラブルシューティングの 1 つとして、API プロキシが意図どおりに展開されていることを確認してください。

API プロキシの展開

API プロキシは、環境に展開されて初めて呼び出せるようになります。API Services は、展開プロセスを管理できるようにする RESTful API を公開します。

以下の API は、Python 展開ツールが代理で呼び出します。この展開ツールは、ローカルに展開する API プロキシのパッケージ化と読み込みをサポートするとともに、既存の API プロキシリビジョンの展開解除も管理します。展開プロセスへの管理を強化する必要がある場合は、以下で説明している直接 API 呼び出しを使用します。

一度に 1 つの環境に展開できる API プロキシのリビジョンは 1 つだけです。そのため、展開済みのリビジョンの展開を解除する必要があります。新しいバンドルを新しいリビジョンとして展開するか、それとも新しいバンドルで既存のリビジョンを上書きするかを管理できます。

The size limit of a proxy bundle is 15 MB.

First undeploy the existing revision. Specify the environment name and the revision number of the API proxy you want to undeploy:

$ curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments \
-u email:password

Then deploy the new revision. The new revision of the API proxy must already exist: 

$ curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments \
-u email:password

Using this approach, there will inevitably be some lag between the time when the first revision is undeployed and the new revision is deployed. During this interval, calls from apps may be rejected with an HTTP code 5xx. If this is a problem, as it usually is in production deployments, use the seamless deployment option, described below.

シームレスな展開 (ダウンタイムなし)

展開中にダウンタイムが生じる可能性を最小限に抑えるには、展開メソッドの override オプションを使用し、それを true に設定します。

API プロキシは、他のリビジョンへの上書き展開はできません。必ず先に展開を解除しておくことが必要です。overridetrue に設定すると、あるリビジョンの API プロキシが現在展開されているリビジョンに上書き展開されるように指示することになります。これにより、展開の手順が逆になります -- 新しいリビジョンが展開され、展開が完了したら、前から展開されていたリビジョンの展開が解除されます。

$ curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments?"override=true" \
-u email:password

delay パラメータを使用すると、展開をさらに最適化できます。delay パラメータは、以前のリビジョンの展開が解除されるまでの時間を秒単位で指定します。これにより、現在処理中のトランザクションには、そのトランザクションを処理する API プロキシの展開が解除される前に処理を完了させる時間が与えられます。override=truedelay パラメータが設定されていると、状況は以下のように進みます。

  • Revision 1 is handling requests.
  • リビジョン 2 が並行して展開されます。
  • リビジョン 2 の展開が完了すると、新しいトラフィックはリビジョン 2 に送られます。リビジョン 1 に新しいトラフィックは送られません。
  • ただし、1 がまだ既存のトランザクションを処理している可能性があります。delay パラメータを例えば 15 秒と設定することで、リビジョン 1 に既存のトランザクションの処理を完了させるためとして 15 秒の猶予を与えられます。
  • 遅延時間が過ぎると、リビジョン 1 の展開が解除されます。
With override set to true, Apigee will not undeploy Revision 1 if the basepath of Revision 1 differs from that of Revision 2. In such a scenario, you will end up having two revisions deployed in the same environment. This can break other plugins and wrappers that make use of the seamless deployment API if you are not accommodating for this scenario in your assertion.
$ curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env-name}/apis/{api_name}/revisions/{revision_number}/deployments?"override=true&delay=15" \
-u email:password
クエリーパラメータ 説明
override

デフォルトは false です (標準の展開動作: 既存のリビジョンの展開が解除されてから、新しいリビジョンが展開されます)。

true に設定すると、標準の展開動作ではなく、シームレスな展開が実施されます。既存のリビジョンが展開されたままの状態で、新しいリビジョンも展開されます。新しいリビジョンが展開されると、古いリビジョンの展開が解除されます。delay パラメータと組み合わせて使用して、展開が解除されるときの動作を管理します。

delay

トランザクションが既存のリビジョンで処理を完了してから展開が解除されるようにします -- そして、502 (不適切なゲートウェイ) エラーや 504 (ゲートウェイタイムアウト) エラーにならないようにします。このパラメータには、展開の解除を遅らせる秒数を指定します。設定できる秒数に上限はなく、秒数を大きく設定することでパフォーマンスに悪影響が及ぶこともありません。この遅延時間中、新しいトラフィックは古いバージョンには一切送られません。

デフォルトは 0 (ゼロ) 秒です。override が true に設定され、delay が 0 の場合、既存のリビジョンの展開は新しいリビジョンが展開されるとすぐに解除されます。負の値は 0 (ゼロ) 秒として扱われます。

override=true に設定し、delay を使用すると、展開中に HTTP 5xx レスポンスがなされなくなります。その理由は、両方の API プロキシリビジョンの展開が同居し、古いほうのリビジョンの展開が遅れて解除されるからです。

API リビジョンのすべての展開の表示

API プロキシの現在展開されているすべてのリビジョンのリストを取得する必要が生じることがあります。

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/weatherapi/revisions/1/deployments \
-u email:password 
{
  "aPIProxy" : "weatherapi",
  "environment" : [ {
    "configuration" : {
      "basePath" : "",
      "steps" : [ ]
    },
    "name" : "test",
    "server" : [ {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "90096dd1-1019-406b-9f42-fbb80cd01200"
    }, {
      "status" : "deployed",
      "type" : [ "message-processor" ],
      "uUID" : "7d6e2eb1-581a-4db0-8045-20d9c3306549"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "1619e2d7-c822-45e0-9f97-63882fb6a805"
    }, {
      "status" : "deployed",
      "type" : [ "router" ],
      "uUID" : "8a5f3d5f-46f8-4e99-b4cc-955875c8a8c8"
    } ],
    "state" : "deployed"
  } ],
  "name" : "1",
  "organization" : "org_name"
}

上図のレスポンスには、Apigee Edge の内部インフラストラクチャ特有のプロパティが多数含まれています。Apigee Edge をオンプレミスで使用している場合を除き、これらの設定は変更できません。

このレスポンスに含まれている重要なプロパティは、organizationenvironmentaPIProxynamestate です。これらのプロパティ値を見ることで、API プロキシの特定リビジョンが環境に展開されていることを確認できます。

test 環境のすべての展開の確認

以下の呼び出しを使用して、特定の環境の展開ステータス (現在展開されている API プロキシのリビジョン番号など) を取得することもできます。

$ curl -u email:password https://api.enterprise.apigee.com/v1/o/{org_name}/environments/test/deployments

これにより、test 環境に展開されているすべての API について、前述と同じ結果が得られます。

組織に存在するすべての展開の表示

すべての環境に現在展開されている全 API プロキシのリビジョンのリストを取得するには、以下の API メソッドを使用します。

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/deployments -u email:password 

これにより、すべての環境に展開されているすべての API プロキシについて、前述と同じ結果が得られます。

API は RESTful なので、POST メソッドを JSON または XML ペイロードと組み合わせて同じリソースに対して使用するだけで、API プロキシを作成できます。

API プロキシのプロファイルが生成されます。API プロキシのデフォルト表現は、JavaScript オブジェクト表記 (JSON) でなされます。以下は、上記の POST リクエストへの JSON レスポンスで、「weatherapi」という API プロキシを作成しています。このプロファイルの各要素について、この後に説明します。

{
  "configurationVersion" : {
    "majorVersion" : 4,
    "minorVersion" : 0
  },
  "contextInfo" : "Revision 1 of application weatherapi, in organization {org_name}",
  "createdAt" : 1357172145444,
  "createdBy" : "you@yourcompany.com",
  "displayName" : "weatherapi",
  "lastModifiedAt" : 1357172145444,
  "lastModifiedBy" : "you@yourcompany.com",
  "name" : "weatherapi",
  "policies" : [ ],
  "proxyEndpoints" : [ ],
  "resources" : [ ],
  "revision" : "1",
  "targetEndpoints" : [ ],
  "targetServers" : [ ],
  "type" : "Application"
}

レスポンスペイロードは API リソースの表現を含んでいるだけであることに注意してください -- API プロキシは JSON または XML で作成でき、API プロキシの表現も、ニーズに応じて、XML または JSON で取得できます。

生成された API プロキシプロファイルは、API プロキシの全体構造を示しています。

  • APIProxy revision: API プロキシ構成の連番付きイテレーション。API Services によって管理されます。
  • APIProxy name: API プロキシの一意の名前。
  • ConfigurationVersion: API プロキシ構成が準拠している API Services バージョン。
  • CreatedAt: API プロキシが生成された時刻。UNIX 時刻形式です。
  • CreatedBy: API プロキシを作成した Apigee Edge ユーザーのメールアドレス。
  • DisplayName: API プロキシのわかりやすい名前。
  • LastModifiedAt: API プロキシの生成時刻。UNIX 時刻形式です。
  • LastModifiedBy: この API プロキシを作成した Apigee Edge ユーザーのメールアドレス。
  • Policies: この API プロキシに追加されているプロパティのリスト。
  • ProxyEndpoints: 名前付き ProxyEndpoints のリスト。
  • Resources: この API プロキシでの実行に使用できるリソースのリスト (JavaScript、Python、Java、XSLT)。
  • TargetServers: (管理 API を使用して作成可能な) 名前付き TargetServers のリスト。高度な構成で負荷分散を目的として使用されます。
  • TargetEndpoints: 名前付き TargetEndpoints のリスト。

上述のシンプルな POST メソッドを使用して作成された API プロキシ構成の要素の多くが空であることに注目してください。以降のトピックでは、API プロキシの主なコンポーネントを追加および構成する手順について見ていきます。

これらの構成要素に関する記載は、「API proxy configuration reference」にもあります。

API に対するスクリプト作成

GitHub の「Using the sample API proxies」には、Apigee 展開ツールをラップするシェルスクリプトが用意されています。何らかの理由で Python 展開ツールを使用できない場合は、この API を直接呼び出せます。どちらのやり方についても、以下のサンプルスクリプトに示されています。

展開ツールのラップ

まず、Python 展開ツールをローカル環境で使用できることを確認します。

次に、資格情報を保持したファイルを作成します。作成する展開スクリプトはこれらの設定を読み込み、アカウントの資格情報を集中管理できるようにします。API Platform サンプルで、このファイルは setenv.sh と呼ばれています。

#!/bin/bash

org="Your ORG on enterprise.apigee.com"
username="Your USERNAME on enterprise.apigee.com"

# While testing, it's not necessary to change the setting below
env="test"
# Change the value below only if you have an on-premise deployment
url="https://api.enterprise.apigee.com"
# Change the value below only if you have a custom domain
api_domain="apigee.net"

export org=$org
export username=$username
export env=$env
export url=$url
export api_domain=$api_domain

上述のファイルは、展開ツールをラップするシェルスクリプトですべての設定を使用できるようにします。

次に、これらの設定を読み込むシェルスクリプトを作成し、それを使用して展開ツールを呼び出します (例についてはこちらを参照)。

#!/bin/bash

source path/to/setenv.sh

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Deploying $proxy to $env on $url using $username and $org

path/to/deploy.py -n {api_name} -u $username:$password -o $org -h $url -e $env -p / -d path/to/apiproxy

物事を簡単にするために、API を呼び出してテストするスクリプトを以下のように作成します。

#!/bin/bash

echo Using org and environment configured in /setup/setenv.sh

source /path/to/setenv.sh

set -x

curl "http://$org-$env.apigee.net/{api_basepath}"

API の直接呼び出し

API プロキシのアップロードと展開の処理を自動化するシンプルなシェルスクリプトを作成すると便利なことがあります。

以下のスクリプトは、管理 API を直接呼び出します。更新している API プロキシについて、既存のリビジョンの展開を解除し、プロキシ構成ファイルを含む /apiproxy ディレクトリを元に ZIP ファイルを作成し、構成をアップロードして、読み込み、展開します。

#!/bin/bash

#This sets the name of the API proxy and the basepath where the API will be available
api=api
	
source /path/to/setenv.sh

echo Delete the DS_store file on OSX

echo find . -name .DS_Store -print0 | xargs -0 rm -rf
find . -name .DS_Store -print0 | xargs -0 rm -rf

echo "Enter your password for the Apigee Enterprise organization $org, followed by [ENTER]:"

read -s password

echo Undeploy and delete the previous revision

# Note that you need to explicitly update the revision to be undeployed. One benefit of the Python deploy tool is that it manages this for you.

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X DELETE

curl -k -u $username:$password -X DELETE "$url/v1/o/$org/apis/$api/revisions/1"

rm -rf $api.zip

echo Create the API proxy bundle and deploy

zip -r $api.zip apiproxy

echo Import the new revision to $env environment 

curl -k -v -u $username:$password "$url/v1/o/$org/apis?action=import&name=$api" -T $api.zip -H "Content-Type: application/octet-stream" -X POST

echo Deploy the new revision to $env environment 

curl -k -u $username:$password "$url/v1/o/$org/e/$env/apis/$api/revisions/1/deployments" -X POST

セキュリティ保護のガイドライン

Edge 管理 API は、HTTP の Basic 認証を採用しています。API 呼び出しごとにユーザー名とパスワードを提供する必要があります。

スクリプトの実行時にパスワード情報を取得するのが現実的でないことがあります。例えば、管理者がいない時に cron ジョブの実行が必要になることが考えられます。そのような場合、スクリプトがパスワードを担当者の介在なしに取得できるようにする必要があります。

以下のガイドラインに従ってください。

  1. 資格情報は単一のファイルにまとめ、作成するプログラムやスクリプトでそれを情報源として使用します。
  2. 資格情報のソースファイルを、ファイルシステムのセキュリティ保護と権限を使用して、できる限り保護します。
  3. 組織内の特定のリソースに対して、権限を大きく制限された自動化クライアントを作成します。

Help or comments?