管理 API を使用した API プロキシのデプロイ

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

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

この管理 API において、自社の SDLC（さらに言えば、あらゆる組織の SDLC）に対する前提条件はありません。逆に、開発担当チームが API 開発ライフサイクルの自動化と最適化を調整できるアトミック関数が公開されています。

管理 API については、API にすべて記載されています。

管理 API を使用するには、呼び出しの中で自身を認証する必要があります。これは、次のいずれかの方法で行えます。

OAuth2（Public Cloud のみ）
SAML（Public Cloud と Private Cloud）
Basic 認証（推奨しません。Public Cloud と Private Cloud）

このトピックでは、API プロキシを管理するための API について説明します。

動画: API をデプロイする方法については、こちらの短い動画をご覧ください。

API とのやり取り

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

組織内の API のリスト化

はじめに、組織の全 API プロキシを一覧にします。email:password と {org_name} の項目は、置き換えてください。手順については、API リファレンススタートガイドをご覧ください。

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.company.com/v1 など）はほとんど変更されません。API のバージョンを上げると、API によって公開されている外部インターフェースの特性に大きな変更があったことがデベロッパーに通知されます。

API プロキシのリビジョンとは、API プロキシ構成に関連付けられている連番にすぎません。API Services は構成のリビジョンを管理して、何か問題が発生した場合には構成を元に戻せるようにしています。デフォルトでは、API プロキシのリビジョンは、新しい API プロキシのインポートの API を使用して API プロキシをインポートするたびに、自動的に増分されます。API プロキシのリビジョンを上げたくない場合は、API プロキシリビジョンのアップデートの API を使用してください。Maven を使用してデプロイする場合は、Maven プラグインの readme の説明に従って、clean または update オプションを使用してください。

たとえば、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 プロキシ構成のリファレンスに詳しく記載されています。

環境への API のデプロイ

リクエストの受信や転送を適切に行うように構成した API プロキシは、1 つまたは複数の環境にデプロイできます。通常、API プロキシは「test」が繰り返され、準備が整うと、その API プロキシのリビジョンが「prod」に昇格されます。たいてい、API プロキシのリビジョンは test 環境のほうが多くなります。prod 環境で繰り返し修正されることはほとんどないためです。

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

環境を一覧表示する方法

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" ]

デプロイの調査

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

API プロキシのデプロイ

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

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

Apigee Edge のドキュメントを表示しています。
Apigee X のドキュメントをご確認ください。情報

まず、既存のリビジョンをデプロイ解除します。デプロイ解除する API プロキシの環境名とリビジョン番号を指定します。

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

次に、新しいリビジョンをデプロイします。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 \
  -u email:password

シームレスなデプロイ（ダウンタイムなし）

デプロイ中にダウンタイムが生じる可能性を最小限に抑えるには、デプロイメソッドの override フォームパラメータを使用し、それを true に設定します。

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

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/apis/api_name/revisions/revision_number/deployments" \
  -d "override=true" \
  -u email:password

delay パラメータを設定することで、デプロイをさらに最適化できます。delay パラメータは、前のリビジョンをデプロイ解除するまでの時間間隔を秒単位で指定します。これにより、現在処理中のトランザクションには、そのトランザクションを処理する API プロキシがデプロイ解除される前に処理を完了させる時間が与えられます。override=true パラメータと delay パラメータを設定すると、次のようになります。

リビジョン 1 はリクエストを処理しています。
リビジョン 2 は並行してデプロイ中です。
リビジョン 2 のデプロイが完了すると、新しいトラフィックはリビジョン 2 に送信されます。リビジョン 1 に新しいトラフィックは送信されません。
ただし、リビジョン 1 はまだ既存のトランザクションを処理している可能性があります。delay パラメータを設定（15 秒など）すると、既存のトランザクションの処理を完了するためにリビジョン 1 に 15 秒が与えられます。
遅延間隔が経過すると、リビジョン 1 がデプロイ解除されます。

注: オーバーライドを true に設定すると、リビジョン 1 のベースパスとリビジョン 2 のベースパスが異なる場合、リビジョン 1 はデプロイ解除されません。このようなシナリオでは、同じ環境に 2 つのリビジョンがデプロイされることになります。これにより、このシナリオのアサーションに対応できない場合、シームレスなデプロイ API を使用する、他のプラグインやラッパーが使えなくなることがあります。

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/org_name/e/env_name/apis/api_name/revisions/revision_number/deployments?delay=15" \
  -d "override=true" \
  -u email:password

クエリパラメータ説明

クエリパラメータ	説明
`override`	デフォルトは false です（標準のデプロイ動作: 既存のリビジョンがデプロイ解除されてから、新しいリビジョンがデプロイされます）。 true に設定すると、標準のデプロイ動作ではなく、シームレスなデプロイが実施されます。既存のリビジョンがデプロイされたままの状態で、新しいリビジョンもデプロイされます。新しいリビジョンがデプロイされると、古いリビジョンはデプロイ解除されます。`delay` パラメータと組み合わせて使用し、デプロイ解除されるときの動作を管理します。
`delay`	トランザクションが既存のリビジョンで処理を完了してからデプロイ解除されるようにし、さらに 502（不適切なゲートウェイ）エラーや 504（ゲートウェイタイムアウト）エラーが発生しないようにするには、このパラメータに、デプロイ解除を遅らせる秒数を指定します。設定できる秒数に上限はなく、秒数を大きく設定することでパフォーマンスに悪影響が及ぶこともありません。この遅延時間中、新しいトラフィックは古いリビジョンには一切送信されません。デフォルトは 0（ゼロ）秒です。`override` が true に設定され、`delay` が 0 の場合、新しいリビジョンがデプロイされるとすぐに既存のリビジョンがデプロイ解除されます。負の値は 0（ゼロ）秒として扱われます。

override

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

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

delay

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

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

delay とともに override=true を使用すると、デプロイ中の 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 をオンプレミスで使用している場合を除き、これらの設定は変更できません。

このレスポンスに含まれる重要なプロパティは、organization、environment、aPIProxy、name、state です。これらのプロパティ値を見ることで、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 プロキシの全体構造を示しています。

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 プロキシ構成のリファレンスにもあります。

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

GitHub のサンプル API プロキシの使用には、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