Hosted Targets チュートリアル

Hosted Targets は Apigee がホストするネイティブの Node.js ランタイム環境です。以降のチュートリアルでは、Hosted Targets を使用して Node.js アプリケーションを Edge にデプロイする方法を説明します。

チュートリアルでは、次のタスクを行います。

  • Edge UI を使用して Node.js アプリを Hosted Targets にデプロイする。
  • ローカルの開発用マシンから Hosted Targets に Node.js アプリをデプロイする。
  • 既存のプロキシと従来の Edge Node.js ターゲット環境を Hosted Targets に移行する

Edge UI を使用して Node.js アプリを Hosted Targets にデプロイする

このチュートリアルでは、Edge UI を使用して簡単な Node.js アプリを Hosted Targets にデプロイします。このチュートリアルを完了すると、Hosted Targets プロキシの基本構造とコンテンツ、デプロイへのアクセス方法、ログファイルの作成方法を理解できます。

ログイン

  1. apigee.com/edge に移動します。
  2. Apigee のログイン認証情報を入力して、ログインします。
  3. Hosted Targets を使用するには、新しい Edge UI が必要です。まだ、準備していない場合は、従来の Edge のナビゲーション バーで [Try New Edge] をクリックします。

新しいプロキシを作成する

  1. サイド ナビゲーション メニューで [Develop] > [API Proxies] の順に選択します。
  2. [+ Proxy] をクリックします。
  3. [Create Proxy] ページで [Hosted Target] を選択します。
  4. [Next] をクリックします。
  5. [Proxy Name] フィールドに hello-hosted-targets を入力します。
  6. "Hello World" Sample が選択されていることを確認します。
  7. [Next] をクリックします。
  8. [Security] ページで、[Authorization] に [Pass through (none)] を選択します。
  9. [Next] をクリックします。
  10. [Next] をクリックします。
  11. [Build] ページで、test 環境が選択されていることを確認します。[Proxy Type] が Hosted Targets になっていることを確認します。
  12. [Build and Deploy] をクリックします。プロキシのデプロイが完了するまでに少し時間がかかることがあります。
  13. プロキシのデプロイに成功したら、ページの下部にある [View hello-hosted-targets proxy] をクリックします。
  14. API プロキシを呼び出します。最も簡単な方法は、[Trace] タブに移動してトレース セッションを開始し、[Send] をクリックする方法です。200 ステータスの次のレスポンスが返されます。
    {"date":"2018-09-26T14:23:04.550Z","msg":"Hello, World!"}

プロキシを調べる

  1. Edge UI で [Develop] タブをクリックします。
  2. ナビゲータで、[Target Endpoints] の [default] を選択します。
  3. コードエディタで、<TargetEndpoint> 要素の下に空の <HostedTarget/> 子要素があることを確認します。この空のタグは必須です。これにより、プロキシのターゲットが Hosted Targets 環境にデプロイされたアプリケーションであることが Edge に通知されます。

  4. ナビゲータで、[Scripts] セクションのコンテンツを確認します。[hosted] というラベルの下に Node.js アプリのファイルが表示されます。

  5. Edge UI で、[Scripts] の [hosted] の下にあるファイルを調べます。
    • app.yaml ファイルには構成情報が含まれています。たとえば、ランタイムに Node.js アプリケーションで使用可能な環境変数を追加できます。この例では、このファイルを修正する必要はありません。
    • index.js ファイルは Node.js アプリのメインファイルです。
    • アプリにモジュールの依存関係が存在する場合、これらの依存関係は package.json に含まれています。

ログファイルを表示する

ビルドフェーズやランタイムに発生した問題のデバッグを行う場合、アプリケーション ログファイルが役に立ちます。

  1. Edge UI で [Develop] タブをクリックします。
  2. ビルドログを表示するには、[Build Logs] をクリックします。
  3. デプロイログを表示するには、[Runtime Logs] をクリックします。

    ログファイルへのアクセスもご覧ください。

まとめ

  • 簡単な Node.js アプリケーションを Hosted Targets 環境にデプロイし、Edge UI でテストを行いました。
  • Hosted Targets プロキシでは、ターゲット エンドポイントに <HostedTarget/> という特別な空タグが必要であることを学習しました。
  • Edge がモジュールの依存関係を自動的に読み込み、依存関係が package.json ファイルに含まれていることを学習しました。
  • ビルドとランタイムのログファイルを確認する方法も学習しました。

システムから Edge に Node.js をデプロイする

このセクションでは、apigeetool を使用して、スタンドアロンの Node.js アプリケーションをローカル システムから Hosted Targets にデプロイする方法を説明します。apigeetool ユーティリティは、Node.js アプリを新しい Hosted Targets プロキシにバンドルし、Edge にデプロイします。

apigeetool をインストールする

開発者がプロキシコードを Edge にデプロイする場合、apigeetool の使用をおすすめします。apigeetool をインストールするには、次の NPM コマンドを実行します。

npm install -g apigeetool

Node.js アプリを作成する

この作業を簡単に行えるように、簡単な Node.js アプリのコードが用意されています。

  1. Node.js アプリのディレクトリを作成します。node-hosted-express ディレクトリを呼び出します。
  2. cd を実行して、新しいディレクトリに移動します。
  3. index.js というファイルを作成して、このコードをコピーします。
  4.     var express = require('express')
        var app = express()
    
        app.get('/', function(req, res) {
            res.json({
                hello: "Hello World!"
            })
        })
    
        app.get('/hello/:name', function(req, res) {
            var name = req.params.name
            res.json({
                hello: "hello " + name
            })
        })
    
        var server = app.listen(process.env.PORT || 9000, function() {
            console.log('Listening on port %d', server.address().port)
        })
        
  5. package.json というファイルを作成し、このファイルに次のコードをコピーします。express モジュールが依存関係として指定されていることに注意してください。
  6.     {
            "name": "hello-world",
            "version": "1.0.0",
            "main": "index.js",
            "scripts": {
                "start": "node index.js --use_strict"
            },
            "author": "",
            "license": "",
            "dependencies": {
                "express": "^4.16.0"
            }
        }
        
  7. app.yaml というファイルを作成し、このファイルに次のコードをコピーします。
  8.     runtime: node
        runtimeVersion: 8
        application: my-express-app
        env:
          - name: NODE_ENV
            value: production
          - name: LOG_LEVEL
            value: 3
        
  9. ディレクトリは次のようになります。
        ls
        app.yaml index.js package.json
        

アプリのコードに必要なディレクトリ構造の確認

Node.js アプリは、標準の Node.js アプリと同じ構造にする必要があります。apigeetool で Edge をデプロイする前に、次の要件を満たしていることを確認してください。

  • app.yaml マニフェスト ファイルが必要です。このファイルがアプリのルート ディレクトリに存在する必要があります。このファイルの詳細については、マニフェスト ファイルをご覧ください。
  • package.json ファイルが必要です。このファイルには、アプリが必要とする依存関係が記述されている必要があります。
  • node_modules フォルダは必須ではありません。Node.js アプリをデプロイすると、Edge が npm install を実行します。さらに、package.json から依存関係を取得します。npm で使用できないカスタム モジュールがある場合にのみ、node_modules を明示的に提供する必要があります。

プロキシのデプロイ

  1. デバイスで cd を実行して、Node.js アプリケーションのルート ディレクトリに移動します。
  2. deployhostedtarget コマンドで apigeetool を実行します。
  3. apigeetool deployhostedtarget -o org -e env -n proxy-name -b /node-hosted-express -u username

    -n には、新しいプロキシの名前を指定します。これは、組織内で一意にする必要があります。名前に使用できる文字は次のとおりです。a-z0-9._\-$ %

    例:

    apigeetool deployhostedtarget -o myorg -e test -n node-hosted-express -b /node-hosted-express -u jdoe@apigee.com

    apigeetool の使用方法については、https://github.com/apigee/apigeetool-node をご覧ください。

プロキシのテスト

プロキシのテストは、cURL コマンド、Postman などの REST クライアント、Edge UI のトレースツールで行うことができます。次の例は cURL コマンドの例です。

curl http://myorg-test.apigee.net/node-hosted-express
         {"date":1506992197427,"msg":"hello-world"}

ビルドログの取得

ビルドログには、Node.js アプリのデプロイとビルドに関連する情報が記録されます。ログファイルもご覧ください。

apigeetool getlogs -u username -o org -e env --hosted-build -n proxy-name

例:

apigeetool getlogs -u jdoe@apigee.com -o myorg -e test --hosted-build -n node-hosted-express

ランタイムログの取得

ランタイムログには、実行中のアプリに関連する出力が記録されます。ランタイムログは環境を対象とし、現在デプロイされているプロキシ リビジョンのログを返します。ログファイルもご覧ください。

apigeetool getlogs -u username -o org -e env --hosted-runtime -n proxy-name

例:

apigeetool getlogs -u jdoe@apigee.com -o myorg -e test --hosted-runtime -n node-hosted-express

Edge UI でのプロキシの表示

デプロイに成功すると、Edge UI の API プロキシ部分にプロキシを表示し、編集できます。

既存の Node.js プロキシの Hosted Targets プロキシへの移行

このセクションでは、従来の Node.js ターゲット環境を利用する既存の Edge API プロキシを Hosted Targets に手動で移行する方法について説明します。また、移行手順を行った後にプロキシをデプロイする方法についても説明します。

移行手順では、API プロキシの構造、ポリシー、フロー、その他の構成要素を維持します。以下で説明するように、移行は 4 つの手順に分けられます。その後、移行したプロキシを apigeetool でデプロイします。

手順 1: プロキシのファイル構造を調整する

ファイル構造を調整するには、API プロキシがローカルのファイル システムに存在している必要があります。プロキシを Edge にデプロイするには、操作を継続する前に、プロキシをダウンロードする必要があります。従来の構成では、Node.js コードを含む Edge プロキシのバンドルは、次のようなファイル構造になっています。Node.js アプリケーションのコードは resources/node ディレクトリにあります。

    apiproxy/
        policies/
        proxies/
        targets/
        resources/
          node/
            Your application code


Hosted Targets の場合、Node.js アプリのルート ディレクトリを resources/hosted というディレクトリの下に配置する必要があります。resources/hosted という新しいディレクトリを作成し、そこに resources/node のコンテンツを移動します。これで resources/node ディレクトリを削除できます。

apiproxy/
         policies/
         proxies/
         targets/
         resources/
           hosted/
             Your application code

手順 2: マニフェスト ファイルを追加する

app.yaml というマニフェスト ファイルを作成して、apiproxy/resources/hosted ディレクトリに配置します。

以下に app.yaml ファイルの例を示します。ここには、ランタイムが Node.js であることが定義されています(必須)。また、実行環境に環境変数(Node.js アプリからアクセスできる変数)が作成されます。環境変数はオプションです。ここでは例として使用しています。詳細については、マニフェスト ファイルをご覧ください。

    runtime: node
      env:
        - name: NODE_ENV
          value: production


次に、Hosted Targets 環境のプロキシで正しい位置に配置された Node.js プロジェクト構造を示します。

    apiproxy/
       resources/
          hosted/
            index.js
            node_modules/
            app.yaml
            package.json

手順 3: package.json ファイルの存在を確認する

従来の Edge Node.js プロキシでは、package.json はオプションです。ただし、Hosted Targets では、apiproxy/resources/hosted ディレクトリに配置する必要があります。このファイルに、アプリで必要となる依存関係を指定します。

手順 4: プロキシのターゲット エンドポイントを変更する

従来の Node.js プロキシでは、ターゲット エンドポイント ファイル(通常は /apiproxy/targets/default.xml)に <ScriptTarget> というタグが必要です。Hosted Targets の場合、<HostedTarget/> という空のタグを追加する必要があります。ファイルに ScriptTarget タグがある場合、このタグを削除できます。例:

        <?xml version="1.0" encoding="UTF-8"?>
        <TargetEndpoint name="default">
           <Description />
           <FaultRules />
           <PreFlow name="PreFlow">
              <Request />
              <Response />
           </PreFlow>
           <PostFlow name="PostFlow">
              <Request />
              <Response />
           </PostFlow>
           <Flows />
           <HostedTarget />
        </TargetEndpoint>
        

プロキシのデプロイ

次に、apigeetool deployproxy コマンドを使用してプロキシをデプロイします。

  1. cd を実行して、プロキシのルート ディレクトリ /apiproxy に移動します。
  2. 次のコマンドでプロキシをデプロイします。
  3. apigeetool deployproxy -u username -o org -e env -n proxy-name -d .

    例:

    apigeetool deployproxy -u jdoe -o docs -e test -n hello-world -d .

apigeetool の使用方法については、https://github.com/apigee/apigeetool-node/blob/master/README.md をご覧ください。

プロキシのテスト

プロキシのテストは、cURL コマンド、Postman などの REST クライアント、Edge UI のトレースツールで行うことができます。次の例は cURL コマンドの例です。

    curl http://myorg-test.apigee.net/hello-world
    Hello,World!