託管目標教學課程

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

以下教學課程說明如何使用託管目標 (由 Apigee 託管的原生 Node.js 執行階段環境) 將 Node.js 應用程式部署至 Edge。

教學課程會逐步介紹以下工作:

  • 使用 Edge UI 將 Node.js 應用程式部署至代管目標。
  • 從本機開發機器將 Node.js 應用程式部署至託管的目標。
  • 將採用傳統邊緣 Node.js 目標實作的現有 Proxy 遷移至代管目標。

使用 Edge UI 將 Node.js 應用程式部署至代管目標

在這個教學課程中,您會使用 Edge UI 將簡單的 Node.js 應用程式部署至代管目標。完成教學課程後,您會瞭解代管目標 Proxy 的基本結構與內容,以及如何存取部署和建構記錄檔。

登入

  1. 前往:apigee.com/edge
  2. 輸入您的 Apigee 登入憑證以登入。

建立新的 Proxy

  1. 在側邊導覽選單中,依序選取「Develop」(開發) >「API Proxy」
  2. 按一下「+ Proxy」
  3. 在「建立 Proxy」頁面中,選取「代管目標」
  4. 按一下「Next」
  5. 在「Proxy Name」欄位中,輸入 hello-hosted-targets
  6. 請務必選取「Hello World」範例
  7. 按一下「Next」
  8. 在「安全性」頁面中,針對授權選取「通過 (無)」
  9. 按一下「Next」
  10. 按一下「Next」
  11. 確認已在「建構」頁面中選取 test 環境。請注意,Proxy 類型為「代管目標」
  12. 按一下「Build and Deploy」。Proxy 部署作業可能需要一些時間才能完成。
  13. Proxy 部署成功後,按一下頁面底部的「View hello-hosted-targets Proxy」
  14. 呼叫 API Proxy。最簡單的做法是前往「Trace」分頁,啟動 Trace 工作階段,然後按一下「Send」。您應該會收到 200 狀態和以下回應:
    {"date":"2018-09-26T14:23:04.550Z","msg":"Hello, World!"}

檢查 Proxy

  1. 在 Edge UI 中,按一下 [Develop] (開發) 分頁標籤。
  2. 在「導覽器」中,選取「目標端點」下方的「預設」
  3. 在程式碼編輯器中,請注意 <TargetEndpoint> 元素下方有一個空白的 <HostedTarget/> 子元素。這是必填欄位。會告知 Edge 的目標 Proxy 是部署至代管目標環境的應用程式。

  4. 請留意「導覽器」中的「指令碼」部分底下的內容。Node.js 應用程式檔案會列在「託管」標籤下。

  5. 在 Edge UI 中,查看「指令碼」底下「代管」底下的檔案:
    • app.yaml 檔案含有設定資訊。舉例來說,您可以新增環境變數,供 Node.js 應用程式在執行階段使用。本範例不需要修改此檔案。
    • index.js 檔案是 Node.js 應用程式的主要檔案。
    • 如果您的應用程式有任何模組依附元件,就必須將這些依附元件列在 package.json 中。

查看記錄檔

應用程式記錄檔有助於對建構階段和執行階段發生的問題進行偵錯。

  1. 在 Edge UI 中,按一下 [Develop] (開發) 分頁標籤。
  2. 如要查看建構記錄檔,請按一下「Build Logs」
  3. 如要查看部署記錄,請按一下「Runtime Logs」(執行階段記錄)。

    另請參閱「存取記錄檔」。

摘要

  • 您已將簡易 Node.js 應用程式部署至代管目標環境,並在 Edge UI 中進行測試。
  • 您已瞭解代管目標 Proxy 需要在目標端點中有一個特殊的空白標記,名為 <HostedTarget/>
  • 您已瞭解 Edge 會自動載入模組依附元件,且依附元件必須列在 package.json 檔案中。
  • 此外,您也學會如何檢查建構和執行階段的記錄檔。

將系統中的 Node.js 從系統部署至 Edge

本節說明如何使用 apigeetool 將獨立的 Node.js 應用程式從本機系統部署至代管目標。apigeetool 公用程式會將 Node.js 應用程式封裝至新的代管目標 Proxy 中,並部署至 Edge。

安裝 apigeetool

我們建議開發人員使用 apigeetool 將 Proxy 程式碼部署至 Edge。如要安裝 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 的檔案,然後將這段程式碼複製到該檔案中。請注意,速成模組會列為依附元件。
  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 取得依附元件。唯一需要明確提供 node_modules 時,如果您的自訂模組無法透過 npm 取得。

部署 Proxy

  1. 在終端機中,cd 傳送至 Node.js 應用程式的根目錄。
  2. 使用 deployhostedtarget 指令執行 apigeetool
  3. apigeetool deployhostedtarget -o org -e env -n proxy-name -b /node-hosted-express -u username

    其中 -n 是您要指派給新 Proxy 的名稱。在機構中不得重複。名稱中使用的字元僅限以下字元: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

測試 Proxy

您可以使用 cURL 指令來測試 Proxy,方法是使用 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

取得執行階段記錄

執行階段記錄檔會顯示與執行中應用程式相關的輸出內容。執行階段記錄檔的範圍會限定在環境,並傳回目前部署的 Proxy 修訂版本記錄檔。另請參閱記錄檔

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 中查看 Proxy

部署成功後,您就能在 Edge UI 的 API Proxy 部分中查看及編輯 Proxy。

將現有的 Node.js Proxy 遷移至代管目標 Proxy

本節說明如何將採用傳統 Node.js 目標實作的現有 Edge API Proxy 手動遷移至代管目標。也會說明如何在執行遷移步驟後部署 Proxy。

遷移步驟會保留 API Proxy 結構、政策、流程和其他設定元素。您可以按照下文所述的四個步驟執行遷移作業,然後使用 apigeetool 部署已遷移的 Proxy。

步驟 1:調整 Proxy 檔案結構

如要調整檔案結構,API Proxy 必須位於本機檔案系統中。如果 Proxy 已部署在 Edge,您必須下載 Proxy 才能繼續操作。在傳統設定中,包含 Node.js 程式碼的 Edge Proxy「套裝組合」遵循這個檔案結構。Node.js 應用程式程式碼位於 resources/node 目錄中:

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


針對代管目標,您必須將 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


以下範例顯示 Node.js 專案結構,且該專案位於代管目標部署 Proxy 的正確位置:

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

步驟 3:確定您擁有 package.json 檔案

在傳統 Edge Node.js Proxy 中,package.json 為選用項目。不過,如果是代管目標,您必須在 apiproxy/resources/hosted 目錄中提供。請務必在這個檔案中為應用程式指定任何必要的依附元件。

步驟 4:修改 Proxy 的目標端點

傳統的 Node.js Proxy 要求目標端點檔案 (通常是 /apiproxy/targets/default.xml) 中包含名為 <ScriptTarget> 的標記。如果是代管目標,您必須新增名為 <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>
    

部署 Proxy

您現在可以使用 apigeetool deployproxy 指令部署 Proxy。

  1. cd 新增至 Proxy 的根目錄:/apiproxy
  2. 使用這個指令部署 Proxy:
  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

測試 Proxy

您可以使用 cURL 指令來測試 Proxy,方法是使用 Postman 等 REST 用戶端,或是追蹤記錄工具中的 Edge UI。cURL 指令範例如下:

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