آموزش‌های گام‌به‌گام «هدف‌های میزبانی‌شده»

درحال مشاهده اسناد Apigee Edge هستید.
به اسناد Apigee X بروید. اطلاعات

آموزش‌های زیر توضیح می‌دهد که چگونه برنامه‌های Node.js را بااستفاده از هدف‌های میزبانی‌شده، یک محیط زمان اجرای Node.js بومی میزبانی‌شده توسط Apigee، در Edge مستقر کنید.

آموزش‌های گام‌به‌گام ازطریق انجام تکالیف زیر شما را راهنمایی می‌کنند:

• استقرار برنامه Node.js در «هدف‌های میزبانی‌شده» بااستفاده از «میانای کاربری Edge».
• استقرار برنامه Node.js در «هدف‌های میزبانی‌شده» از ماشین توسعه محلی.
• انتقال کارگزار پراکسی موجود با پیاده‌سازی هدف Node.js سنتی Edge به «هدف‌های میزبانی‌شده».

استقرار برنامه Node.js در «هدف‌های میزبانی‌شده» بااستفاده از «میانای کاربر Edge»

در این آموزش، یک برنامه Node.js ساده را بااستفاده از Edge UI در «هدف‌های میزبانی‌شده» مستقر خواهید کرد. پس‌از تکمیل آموزش گام‌به‌گام، با ساختار و محتوای پایه کارگزار نیابت «هدف‌های میزبانی‌شده» و نحوه دسترسی به فایل‌های گزارش ساخت و استقرار آشنا خواهید شد.

ورود به سیستم

1. به این نشانی بروید: apigee.com/edge
2. برای ورود به سیستم، اطلاعات اعتباری ورود به سیستم Apigee را وارد کنید.

ایجاد پراکسی جدید

1. در منو پیمایش کناری، توسعه > پراکسی‌های API را انتخاب کنید.
2. روی + پراکسی کلیک کنید.
3. در صفحه «ایجاد پراکسی»، هدف میزبانی‌شده را انتخاب کنید.
4. روی بعدی کلیک کنید.
5. در فیلد «نام پراکسی»، hello-hosted-targets را وارد کنید.
6. مطمئن شوید که نمونه «سلام دنیا» انتخاب شده باشد.
7. روی بعدی کلیک کنید.
8. در صفحه «امنیت»، عبور (هیچ) را برای «مجوز» انتخاب کنید.
9. روی بعدی کلیک کنید.
10. روی بعدی کلیک کنید.
11. در صفحه «ساخت»، مطمئن شوید که محیط آزمایش انتخاب شده است. توجه داشته باشید که «نوع پراکسی» هدف‌های میزبانی‌شده است.
12. روی ساختن و پیاده‌سازی کلیک کنید. ممکن است چند لحظه طول بکشد تا استقرار پراکسی تکمیل شود.
13. پس‌از اینکه پراکسی با موفقیت مستقر شد، در پایین صفحه روی مشاهده پراکسی هدف‌های میزبانی‌شده سلام کلیک کنید.
14. پراکسی API را فراخوانی کنید. ساده‌ترین راه برای انجام این کار این است که به برگه ردیابی بروید، جلسه «ردیابی» را شروع کنید، و روی ارسال کلیک کنید. باید وضعیت ۲۰۰ را با پاسخ زیر دریافت کنید: پاسخ:

    {"date":"2018-09-26T14:23:04.550Z","msg":"Hello, World!"}

بررسی پراکسی

1. در «واسط کاربر Edge»، روی زبانه توسعه کلیک کنید.
2. در «پیمایشگر»، پیش‌فرض را در «نقطه‌های پایانی هدف» انتخاب کنید.
3. در ویرایشگر کد، متوجه شوید که عنصر فرزند <HostedTarget/> خالی زیر عنصر <TargetEndpoint> وجود دارد. این برچسب خالی الزامی است. به Edge می‌گوید که هدف پراکسی برنامه‌ای است که در محیط «هدف‌های میزبانی‌شده» مستقر شده است.

   

4. در «پیمایشگر»، محتوای زیر بخش نوشتارها را مشاهده کنید. فایل‌های برنامه Node.js در زیر برچسب میزبانی‌شده فهرست شده‌اند.

   

5. در «میانای کاربری Edge»، فایل‌های فهرست‌شده در بخش میزبانی‌شده در نوشته‌ها را بررسی کنید:
• فایل app.yaml حاوی اطلاعات پیکربندی است. برای مثال، می‌توانید متغیرهای محیطی را اضافه کنید که در زمان اجرا برای برنامه Node.js دردسترس خواهند بود. برای این مثال نیازی نیست این فایل را تغییر دهید.
• فایل index.js فایل اصلی برنامه Node.js است.
• اگر برنامه شما وابستگی‌های واحد دارد، باید در package.json فهرست شوند.

مشاهده فایل‌های گزارش

فایل‌های گزارش برنامه می‌توانند برای اشکال‌زدایی مشکلات رخ‌داده در مرحله ساخت و همچنین در زمان اجرا مفید باشند.

1. در واسط کاربر Edge، روی زبانه توسعه کلیک کنید.
2. برای دیدن گزارش ساخت، روی گزارش‌های ساخت کلیک کنید.
3. برای دیدن گزارش استقرار، روی گزارش‌های زمان اجرا کلیک کنید.
   
   همچنین ببینید دسترسی به فایل‌های گزارش.

خلاصه

• یک برنامه ساده Node.js را در محیط «هدف‌های میزبانی‌شده» مستقر کردید و آن را در «واسط کاربر Edge» آزمایش کردید.
• یاد گرفتید که کارگزار «هدف‌های میزبانی‌شده» به برچسب خالی ویژه‌ای در «نقطه پایانی هدف» به‌نام <HostedTarget/> نیاز دارد.
• یاد گرفتید که Edge وابستگی‌های واحد را به‌طور خودکار برایتان بار می‌کند و وابستگی‌ها باید در فایل package.json فهرست شوند.
• همچنین با نحوه بررسی فایل‌های گزارش ساخت و زمان اجرا آشنا شدید.

استقرار Node.js از سیستم در Edge

این بخش توضیح می‌دهد که چگونه برنامه Node.js مستقل را از سیستم محلی‌تان به «هدف‌های میزبانی‌شده» بااستفاده از apigeetool مستقر کنید. ابزار apigeetool برنامه Node.js را در پراکسی «هدف‌های میزبانی‌شده» جدیدی دسته‌بندی می‌کند و آن را در Edge مستقر می‌کند.

نصب apigeetool

استفاده از apigeetool روش توصیه‌شده برای توسعه‌دهندگان جهت استقرار کد پراکسی در Edge است. برای نصب apigeetool، فرمان NPM زیر را اجرا کنید:

npm install -g apigeetool

ایجاد برنامه Node.js

برای آسان‌تر شدن کار، کد یک برنامه ساده Node.js دراختیارتان قرار داده شده است.

1. دایرکتوری برای برنامه Node.js ایجاد کنید. دایرکتوری را node-hosted-express بنامید.
2. بااستفاده از دستور cd به فهرست راهنمای جدید بروید.
3. فایلی به‌نام index.js ایجاد کنید و این کد را در آن کپی کنید.

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 به‌عنوان وابستگی فهرست شده است.

{
    "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 ایجاد کنید و این کد را در آن کپی کنید:

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 الزامی نیست. وقتی برنامه Node.js مستقر می‌شود، Edge به‌طور خودکار npm install را برای شما اجرا می‌کند. وابستگی‌ها را از package.json دریافت می‌کند. تنها زمانی که باید به‌طور صریح node_modules را ارائه دهید این است که ماژول‌های سفارشی داشته باشید که ازطریق npm دردسترس نباشند.

درحال مستقر کردن پراکسی

1. در پایانه، بااستفاده از cd به دایرکتوری ریشه برنامه Node.js بروید.
2. apigeetool را با فرمان deployhostedtarget اجرا کنید:

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، با مشتری REST مانند Postman، یا در 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»

پس‌از استقرار موفقیت‌آمیز، می‌توانید کارگزار نیابتی خود را در بخش «کارگزارهای نیابتی API» در «واسط کاربر Edge» مشاهده و ویرایش کنید.

انتقال دادن پراکسی Node.js موجود به پراکسی «هدف‌های میزبانی‌شده»

این بخش توضیح می‌دهد که چگونه یک پراکسی Edge API موجود را که از پیاده‌سازی هدف Node.js سنتی استفاده می‌کند به‌صورت دستی به «هدف‌های میزبانی‌شده» انتقال دهید. همچنین نحوه استقرار پراکسی پس‌از انجام مراحل انتقال را توضیح می‌دهد.

مراحل انتقال ساختار، خط‌مشی‌ها، جریان‌ها، و دیگر عناصر پیکربندی کارگزار نیابتی API را حفظ می‌کند. می‌توانید انتقال را در چهار مرحله، همان‌طور که در زیر توضیح داده شده است، انجام دهید و سپس کارگزار وکالتی منتقل‌شده را با apigeetool مستقر کنید.

مرحله ۱: ساختار فایل پراکسی را اصلاح کنید

برای اصلاح ساختار فایل، پراکسی API باید در سیستم فایل محلی شما باشد. اگر پراکسی در Edge توزیع شده است، باید قبل‌از ادامه دادن، آن را بارگیری کنید. در پیکربندی سنتی، و پراکسی Edge «بسته‌ای» که شامل کد Node.js است از این ساختار فایل پیروی می‌کند. کد برنامه 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

مرحله ۲: افزودن فایل مانیفست

فایل مانیفستی به‌نام app.yaml ایجاد کنید و آن را در apiproxy/resources/hosted دایرکتوری قرار دهید.

در زیر نمونه‌ای از فایل app.yaml آورده شده است. مشخص می‌کند که زمان اجرا Node.js است (الزامی). همچنین متغیر محیطی در محیط اجرا ایجاد می‌کند (متغیری که برنامه Node.js می‌تواند به آن دسترسی داشته باشد). متغیر محیط اختیاری است و فقط به‌عنوان نمونه در اینجا نشان داده می‌شود. برای جزئیات بیشتر و مثال‌ها، به فایل مانیفست مراجعه کنید.

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

مثال زیر ساختار پروژه Node.js را نشان می‌دهد که در مکان صحیح در پراکسی برای استقرار «هدف‌های میزبانی‌شده» قرار دارد:

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

مرحله ۳: مطمئن شوید فایل package.json دارید

در پراکسی‌های سنتی Edge Node.js،‏ package.json اختیاری بود. بااین‌حال، برای «هدف‌های میزبانی‌شده»، باید یکی را در دایرکتوری apiproxy/resources/hosted ارائه دهید. حتماً وابستگی‌های موردنیاز برنامه‌تان را در این فایل مشخص کنید.

مرحله ۴: اصلاح نقطه پایان هدف پراکسی

کارگزار سنتی Node.js نیاز دارد که برچسبی به‌نام <ScriptTarget> در فایل نقطه پایانی هدف (معمولاً /apiproxy/targets/default.xml) وجود داشته باشد. برای «هدف‌های میزبانی‌شده»، باید برچسب خالی به‌نام <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. از این فرمان برای استقرار پراکسی استفاده کنید:

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، با مشتری REST مانند Postman، یا در Edge UI در ابزار «پیگیری» آزمایش کنید. در اینجا یک فرمان cURL نمونه آورده شده است:

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