מדריכי יעדים מתארחים

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

במדריכים הבאים מוסבר איך לפרוס אפליקציות Node.js ב-Edge באמצעות Hosted Targets, סביבת זמן ריצה מקורית של Node.js שמארחת Apigee.

במדריכים מוסבר איך לבצע את המשימות הבאות:

  • פריסת אפליקציית Node.js ב-Hosted Targets באמצעות Edge UI.
  • פריסת אפליקציית Node.js ב-Hosted Targets ממחשב הפיתוח המקומי.
  • העברה של שרת proxy קיים עם הטמעה מסורתית של יעד Node.js ב-Edge אל Hosted Targets.

פריסת אפליקציית Node.js ליעדים מתארחים באמצעות Edge UI

במדריך הזה נסביר איך לפרוס אפליקציית Node.js פשוטה ליעדים מתארחים באמצעות ממשק המשתמש של Edge. בסיום ההדרכה תבינו את המבנה הבסיסי ואת התוכן של פרוקסי Hosted Targets, ותדעו איך לגשת לקבצי יומן של פריסה ובנייה.

כניסה לחשבון

  1. נכנסים לכתובת: apigee.com/edge
  2. מזינים את פרטי הכניסה ל-Apigee כדי להיכנס.

יצירת שרת proxy חדש

  1. בתפריט הניווט הצדדי, בוחרים באפשרות פיתוח > שרתי proxy של API.
  2. לוחצים על + שרת proxy.
  3. בדף 'יצירת שרת proxy', בוחרים באפשרות Hosted Target (יעד מתארח).
  4. לוחצים על הבא.
  5. בשדה 'שם שרת Proxy', מזינים hello-hosted-targets.
  6. מוודאים שהאפשרות "Hello World" Sample (דוגמה ל-Hello World) נבחרה.
  7. לוחצים על הבא.
  8. בדף 'אבטחה', בוחרים באפשרות העברה (ללא) בקטע 'הרשאה'.
  9. לוחצים על הבא.
  10. לוחצים על הבא.
  11. בדף Build, מוודאים שבחרתם בסביבת test. שימו לב שסוג ה-Proxy הוא Hosted Targets.
  12. לוחצים על Build and Deploy (בנייה ופריסה). יכול להיות שיעברו כמה רגעים עד שהפריסה של ה-Proxy תושלם.
  13. אחרי שה-proxy נפרס בהצלחה, לוחצים על View hello-hosted-targets proxy בתחתית הדף.
  14. שליחת קריאה ל-proxy ל-API. הדרך הכי קלה לעשות את זה היא לעבור לכרטיסייה Trace, להתחיל סשן Trace וללחוץ על Send. אמורים לקבל סטטוס 200 עם התגובה הבאה: 
    {"date":"2018-09-26T14:23:04.550Z","msg":"Hello, World!"}

בדיקת ה-proxy

  1. בממשק המשתמש של Edge, לוחצים על הכרטיסייה פיתוח.
  2. בחלונית הניווט, בוחרים באפשרות default (ברירת מחדל) בקטע Target Endpoints (נקודות קצה של יעד).
  3. בעורך הקוד, שימו לב שיש אלמנט צאצא ריק <HostedTarget/> מתחת לאלמנט <TargetEndpoint>. חובה להוסיף את התג הריק הזה. היא מציינת ל-Edge שיעד ה-proxy הוא אפליקציה שנפרסה בסביבת Hosted Targets.

  4. בסרגל הניווט, שימו לב לתוכן בקטע Scripts (סקריפטים). הקבצים של אפליקציית Node.js מופיעים תחת התווית hosted.

  5. בממשק המשתמש של Edge, בודקים את הקבצים שמופיעים בקטע hosted שבScripts:
    • קובץ ה-app.yaml מכיל פרטי הגדרה. לדוגמה, אפשר להוסיף משתני סביבה שיהיו זמינים לאפליקציית Node.js בזמן הריצה. אין צורך לשנות את הקובץ הזה בדוגמה הזו.
    • הקובץ index.js הוא הקובץ הראשי של אפליקציית Node.js.
    • אם לאפליקציה יש יחסי תלות במודולים, הם צריכים להופיע בקובץ package.json.

צפייה בקובצי יומן

קבצים של יומני רישום של אפליקציות יכולים להיות שימושיים לניפוי באגים בבעיות שמתרחשות במהלך שלב הבנייה וגם בזמן הריצה.

  1. בממשק המשתמש של Edge, לוחצים על הכרטיסייה פיתוח.
  2. כדי לראות את יומן הבנייה, לוחצים על Build Logs (יומני בנייה).
  3. כדי לראות את יומן הפריסה, לוחצים על Runtime Logs (יומני זמן ריצה).

    מידע נוסף גישה לקובצי יומן

סיכום

  • פרסתם אפליקציית Node.js פשוטה בסביבת Hosted Targets ובדקתם אותה בממשק המשתמש של Edge.
  • למדתם שפרוקסי של Hosted Targets דורש תג ריק מיוחד ב-Target Endpoint שנקרא <HostedTarget/>.
  • למדתם ש-Edge טוען באופן אוטומטי את יחסי התלות של המודולים, ושיחסי התלות צריכים להופיע בקובץ package.json.
  • למדתם גם איך לבדוק את קובצי היומן של הבנייה ושל זמן הריצה.

פריסת Node.js מהמערכת אל Edge

בקטע הזה מוסבר איך לפרוס אפליקציית Node.js עצמאית מהמערכת המקומית אל Hosted Targets באמצעות apigeetool. הכלי apigeetool מאגד את אפליקציית Node.js לפרוקסי חדש של Hosted Targets ופורס אותה ב-Edge.

התקנה של apigeetool

הדרך המומלצת למפתחים לפרוס קוד של שרת proxy ב-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)
})
  4. יוצרים קובץ בשם package.json ומעתיקים אליו את הקוד הזה. שימו לב שהמודול express מופיע כ-dependency. 
    5. {
    "name": "hello-world",
    "version": "1.0.0",
    "main": "index.js",
    "scripts": {
        "start": "node index.js --use_strict"
    },
    "author": "",
    "license": "",
    "dependencies": {
        "express": "^4.16.0"
    }
}
  5. יוצרים קובץ בשם app.yaml ומעתיקים אליו את הקוד הזה:
    6. runtime: node
runtimeVersion: 8
application: my-express-app
env:
  - name: NODE_ENV
    value: production
  - name: LOG_LEVEL
    value: 3
  6. ודאו שהספרייה נראית כך: 
    ls
app.yaml index.js package.json

סקירה של מבנה הספריות הנדרש לקוד האפליקציה

לאפליקציית Node.js שלכם צריך להיות מבנה זהה למבנה של אפליקציית Node.js רגילה. עם זאת, חשוב לוודא שפעלתם בהתאם לדרישות הבאות לפני הפריסה באמצעות apigeetool אל Edge:

  • קובץ המניפסט app.yaml הוא קובץ חובה, והוא צריך להיות בתיקיית השורש של האפליקציה. מידע נוסף על הקובץ הזה זמין במאמר בנושא קובץ מניפסט.
  • נדרש קובץ package.json. צריך לציין את כל יחסי התלות שהאפליקציה דורשת.
  • לא חובה להשתמש בתיקייה node_modules. ‫Edge מריץ את הפקודה npm install בשבילכם כשפורסים את אפליקציית Node.js. הוא מקבל את יחסי התלות מ-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 הוא השם שרוצים לתת לפרוקסי החדש. הוא חייב להיות ייחודי בארגון. התווים שמותר להשתמש בהם בשם מוגבלים לאפשרויות הבאות: 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, באמצעות לקוח REST כמו Postman או בממשק המשתמש של Edge בכלי Trace. זוהי דוגמה לפקודת cURL.

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

איך מקבלים את יומני הבנייה

ביומני ה-build מוצגות תוצאות שקשורות לפריסה ול-build של אפליקציית 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

הצגת ה-proxy בממשק המשתמש של Edge

אחרי פריסה מוצלחת, אפשר לראות ולערוך את ה-proxy בחלק API Proxies (שרתי proxy של API) בממשק המשתמש של Edge.

העברת שרת proxy קיים של Node.js לשרת proxy של Hosted Targets

בקטע הזה מוסבר איך להעביר ידנית שרת proxy קיים של Edge API שמשתמש בהטמעה מסורתית של יעד Node.js אל Hosted Targets. בנוסף, נסביר איך לפרוס את ה-proxy אחרי שמבצעים את שלבי ההעברה.

במהלך שלבי ההעברה נשמרים המבנה, המדיניות, התהליכים ורכיבי ההגדרה האחרים של proxy ל-API. אפשר לבצע את ההעברה בארבעה שלבים, כמו שמתואר בהמשך, ואז לפרוס את ה-proxy שהועבר באמצעות apigeetool.

שלב 1: משנים את מבנה קובץ ה-Proxy

כדי לשנות את מבנה הקובץ, צריך ש-proxy ל-API יהיה במערכת הקבצים המקומית. אם ה-proxy נפרס ב-Edge, צריך להוריד אותו לפני שממשיכים. בתצורה הרגילה, 'חבילה' של Edge proxy שכוללת קוד Node.js פועלת לפי מבנה הקובץ הזה. קוד האפליקציה של 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


בדוגמה הבאה מוצג מבנה של פרויקט Node.js שנמצא במיקום הנכון בפרוקסי לצורך פריסה של Hosted Targets:

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

שלב 3: מוודאים שיש לכם קובץ package.json

בשרתי proxy מסורתיים של Edge Node.js, הפרמטר package.json היה אופציונלי. עם זאת, כשמדובר ביעדים מתארחים, צריך לספק אחד בספרייה apiproxy/resources/hosted. חשוב לציין בקובץ הזה את כל יחסי התלות הנדרשים של האפליקציה.

שלב 4: משנים את נקודת הקצה של השרת הפרוקסי

בשרת proxy מסוג Node.js רגיל, צריך להוסיף תג בשם <ScriptTarget> לקובץ של נקודת היעד (בדרך כלל /apiproxy/targets/default.xml). ב-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>

פריסת ה-proxy

עכשיו אפשר לפרוס את ה-Proxy באמצעות הפקודה apigeetool deployproxy.

  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, באמצעות לקוח REST כמו Postman או בממשק המשתמש של Edge בכלי Trace. זוהי דוגמה לפקודת cURL:

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