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

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

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

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

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

管理 API を使用するには、呼び出しを通じて自社を認証する必要があります。これは、次のいずれかの方法で行うことができます。

  • OAuth2(Public Cloud のみ)
  • SAML(Public Could と Private Cloud)
  • 基本認証(推奨しません。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 つだけです。そのため、展開済みのリビジョンの展開を解除する必要があります。新しいバンドルを新しいリビジョンとして展開するか、それとも新しいバンドルで既存のリビジョンを上書きするかを管理できます。

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

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 パラメータが設定されていると、状況は以下のように進みます。

  • リビジョン 1 はリクエストを処理しています。
  • リビジョン 2 は並行して展開中です。
  • リビジョン 2 の展開が完了すると、新しいトラフィックはリビジョン 2 に送信されます。リビジョン 1 に新しいトラフィックは送信されません。
  • ただし、リビジョン 1 はまだ既存のトランザクションを処理している可能性があります。delay パラメータをたとえば 15 秒と設定すると、リビジョン 1 に既存のトランザクションの処理を完了させる時間が 15 秒与えられます。
  • 遅延時間が経過すると、リビジョン 1 の展開が解除されます。
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(ゼロ)秒として扱われます。

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 をオンプレミスで使用している場合を除き、これらの設定は変更できません。

レスポンスに含まれる重要なプロパティは、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 プロキシの全体構造を示しています。

  • 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 プロキシのアップロードと展開の処理を自動化するシンプルなシェル スクリプトを作成しておくと便利です。

以下のスクリプトは、Management 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