پراکسی های API را با استفاده از API مستقر کنید

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

هر سازمانی چرخه عمر توسعه نرم‌افزار (SDLC) منحصر به فردی دارد. اغلب لازم است که استقرار پروکسی API با فرآیندهای مورد استفاده برای سرویس‌های backend هماهنگ و همسو شود.

روش‌های API Edge که در این مبحث نشان داده شده‌اند، می‌توانند برای ادغام مدیریت پروکسی API در SDLC سازمان شما مورد استفاده قرار گیرند. یکی از کاربردهای رایج این API، نوشتن اسکریپت‌ها یا کدهایی است که پروکسی‌های API را مستقر می‌کنند، یا پروکسی‌های API را از یک محیط به محیط دیگر منتقل می‌کنند، به عنوان بخشی از یک فرآیند خودکار بزرگتر که برنامه‌های دیگر را نیز مستقر یا منتقل می‌کند.

رابط برنامه‌نویسی کاربردی Edge هیچ فرضی در مورد SDLC شما (یا هر کس دیگری) ندارد. در عوض، توابع اتمی را در معرض نمایش قرار می‌دهد که می‌توانند توسط تیم توسعه شما هماهنگ شوند تا چرخه عمر توسعه API شما را خودکار و بهینه کنند.

برای اطلاعات کامل، به Edge APIs مراجعه کنید.

برای استفاده از Edge API، باید در تماس‌های خود احراز هویت کنید. می‌توانید این کار را با یکی از روش‌های زیر انجام دهید:

• OAuth2 (فقط ابر عمومی)
• SAML (ابر عمومی و خصوصی)
• مجوز پایه (توصیه نمی‌شود؛ فضای ابری عمومی و خصوصی)

این مبحث بر روی مجموعه APIهایی که برای مدیریت پروکسی‌های API هستند، تمرکز دارد.

ویدیو: برای یادگیری نحوه استقرار API، این ویدیوی کوتاه را ببینید.

تعامل با API

مراحل زیر شما را در تعاملات ساده با APIها راهنمایی می‌کند.

API های موجود در سازمان خود را فهرست کنید

می‌توانید با فهرست کردن تمام پراکسی‌های API در سازمان خود شروع کنید. (به یاد داشته باشید که ورودی‌ها را به جای EMAIL:PASSWORD و ORG_NAME قرار دهید. برای دستورالعمل‌ها، به بخش «استفاده از API Edge» مراجعه کنید.)

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/apis

پاسخ نمونه:

[ "weatherapi" ]

دریافت API

شما می‌توانید متد GET را روی هر پروکسی API در سازمان خود فراخوانی کنید. این فراخوانی لیستی از تمام نسخه‌های موجود پروکسی 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 را در محیط تولید مستقر کنید، در حالی که به ایجاد نسخه‌های جدید از آن پروکسی API در محیط تست ادامه می‌دهید. وقتی آماده شدید، می‌توانید نسخه بالاتر پروکسی API خود را از محیط تست نسبت به نسخه قبلی پروکسی API در محیط تولید ارتقا دهید .

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

دریافت نسخه API

نسخه API (برای مثال، api.company.com/v1 ) باید خیلی کم تغییر کند. وقتی نسخه API را افزایش می‌دهید، برای توسعه‌دهندگان این معنی را دارد که تغییر قابل توجهی در امضای رابط خارجیِ در معرض API رخ داده است.

نسخه پروکسی API یک عدد افزایشی است که با پیکربندی پروکسی API مرتبط است. سرویس‌های API نسخه‌های پیکربندی شما را نگهداری می‌کنند تا بتوانید در صورت بروز مشکل، پیکربندی را به حالت اولیه برگردانید. به طور پیش‌فرض، هر بار که یک پروکسی API را با استفاده از Import an API proxy API وارد می‌کنید، نسخه پروکسی API به طور خودکار افزایش می‌یابد. اگر نمی‌خواهید نسخه یک پروکسی API را افزایش دهید، از Update API proxy revision API استفاده کنید. اگر از Maven برای استقرار استفاده می‌کنید، از گزینه‌های clean یا update ، همانطور که در readme افزونه Maven توضیح داده شده است، استفاده کنید.

برای مثال، می‌توانید متد GET را در نسخه ۱ پروکسی API فراخوانی کنید تا نمای دقیقی از آن داشته باشید.

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 شما برای دریافت و ارسال درخواست‌ها، می‌توانید آن را در یک یا چند محیط مستقر کنید. معمولاً، شما پروکسی‌های API را در test تکرار می‌کنید و سپس، وقتی آماده شدید، نسخه پروکسی API را به prod ارتقا می‌دهید . اغلب، متوجه خواهید شد که نسخه‌های بسیار بیشتری از یک پروکسی API در محیط تست دارید، در درجه اول به این دلیل که در محیط تولید تکرار بسیار کمتری انجام خواهید داد.

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

نحوه فهرست کردن محیط‌ها

هر سازمانی در Apigee Edge حداقل دو محیط دارد: test و prod . تمایز بین این دو دلخواه است. هدف این است که قبل از اینکه پروکسی API خود را برای توسعه‌دهندگان خارجی باز کنید، فضایی برای تأیید صحت عملکرد آن در اختیار شما قرار گیرد.

هر محیط در واقع فقط یک آدرس شبکه است که به شما امکان می‌دهد ترافیک را بین پروکسی‌های API که روی آنها کار می‌کنید و آنهایی که توسط برنامه‌ها در زمان اجرا قابل دسترسی هستند، تفکیک کنید.

محیط‌ها همچنین امکان جداسازی داده‌ها و منابع را فراهم می‌کنند. به عنوان مثال، می‌توانید حافظه‌های پنهان (cache) مختلفی را در تست و تولید تنظیم کنید که فقط توسط پروکسی‌های API که در آن محیط اجرا می‌شوند، قابل دسترسی باشند.

مشاهده محیط‌های یک سازمان

curl -u EMAIL:PASSWORD \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments

پاسخ نمونه

[ "test", "prod" ]

کاوش در استقرارها

یک استقرار ، نسخه‌ای از یک پروکسی API است که در یک محیط مستقر شده است. یک پروکسی API که در حالت مستقر قرار دارد، از طریق شبکه و در آدرس‌های تعریف شده در عنصر <VirtualHost> برای آن محیط قابل دسترسی است.

استقرار پروکسی‌های API

پروکسی‌های API تا زمانی که مستقر نشده‌اند، قابل فراخوانی نیستند. سرویس‌های API، APIهای RESTful را در معرض نمایش قرار می‌دهند که کنترل فرآیند استقرار را فراهم می‌کنند.

فقط یک نسخه از یک پروکسی API می‌تواند در یک زمان معین در یک محیط مستقر شود. بنابراین، نسخه مستقر شده باید از حالت استقرار خارج شود. شما می‌توانید کنترل کنید که آیا بسته جدید به عنوان یک نسخه جدید مستقر شود یا اینکه نسخه موجود را بازنویسی کند.

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

ابتدا نسخه موجود را از حالت استقرار خارج کنید. نام محیط و شماره نسخه پروکسی 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 را روی نسخه دیگر مستقر کنید. نسخه اول همیشه باید مستقر نباشد. با تنظیم override روی true ، شما نشان می‌دهید که یک نسخه از یک پروکسی API باید روی نسخه مستقر شده فعلی مستقر شود. نتیجه این است که توالی استقرار معکوس می‌شود - نسخه جدید مستقر می‌شود و پس از اتمام استقرار، نسخه مستقر شده قبلی مستقر نمی‌شود.

مثال زیر مقدار override را با ارسال آن به عنوان پارامتر فرم، تنظیم می‌کند:

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments" \
  -d "override=true" \
  -u EMAIL:PASSWORD

شما می‌توانید با تنظیم پارامتر delay ، پیاده‌سازی را بهینه‌تر کنید. پارامتر delay یک بازه زمانی (بر حسب ثانیه) را مشخص می‌کند که قبل از آن، نسخه قبلی باید پیاده‌سازی نشده باشد. نتیجه این است که تراکنش‌های درون برنامه‌ای، یک بازه زمانی دارند که باید قبل از پردازش پروکسی API و غیرفعال شدن تراکنش، تکمیل شوند. در ادامه، اتفاقی که با override=true و تنظیم پارامتر delay رخ می‌دهد، آمده است:

• ویرایش ۱ در حال رسیدگی به درخواست‌ها است.
• نسخه ۲ به صورت موازی در حال پیاده‌سازی است.
• وقتی نسخه ۲ به طور کامل مستقر شد، ترافیک جدید به نسخه ۲ ارسال می‌شود. هیچ ترافیک جدیدی به نسخه ۱ ارسال نمی‌شود.
• با این حال، نسخه ۱ ممکن است هنوز در حال پردازش تراکنش‌های موجود باشد. با تنظیم پارامتر delay (مثلاً ۱۵ ثانیه)، به نسخه ۱، ۱۵ ثانیه فرصت می‌دهید تا پردازش تراکنش‌های موجود را به پایان برساند.
• پس از فاصله تأخیر، نسخه ۱ غیرفعال است.

curl -X POST -H "Content-type:application/x-www-form-urlencoded" \
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/e/ENV_NAME/apis/API_NAME/revisions/REVISION_NUMBER/deployments?delay=15" \
  -d "override=true" \
  -u EMAIL:PASSWORD

وقتی override=true به همراه یک delay استفاده شود، پاسخ‌های HTTP 5XX در طول استقرار می‌توانند حذف شوند. دلیل این امر این است که هر دو نسخه پروکسی API به طور همزمان مستقر می‌شوند و نسخه قدیمی‌تر پس از تأخیر مستقر نمی‌شود.

مشاهده‌ی تمام پیاده‌سازی‌های یک نسخه از API Revision

گاهی اوقات لازم است لیستی از تمام نسخه‌های فعلیِ یک پروکسی 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 به صورت داخلی استفاده کنید، نمی‌توانید این تنظیمات را تغییر دهید.

ویژگی‌های مهم موجود در پاسخ عبارتند از organization ، environment ، aPIProxy ، name و state . با بررسی مقادیر این ویژگی‌ها، می‌توانید تأیید کنید که یک نسخه خاص از یک API proxy در یک محیط مستقر شده است.

مشاهده تمام استقرارها در محیط آزمایشی

همچنین می‌توانید وضعیت استقرار را برای یک محیط خاص (از جمله شماره ویرایش پروکسی API مستقر شده فعلی) با استفاده از فراخوانی زیر بازیابی کنید:

curl -u EMAIL:PASSWORD
  https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments/test/deployments

این برای هر API مستقر در محیط آزمایش، همان نتیجه فوق را برمی‌گرداند

مشاهده تمام استقرارها در سازمان شما

برای دریافت لیستی از تمام نسخه‌های پیاده‌سازی‌شده‌ی فعلیِ تمام پروکسی‌های API در تمام محیط‌ها، از متد API زیر استفاده کنید:

curl https://api.enterprise.apigee.com/v1/o/ORG_NAME/deployments \
  -u EMAIL:PASSWORD

این دستور، همان نتیجه‌ی بالا را برای تمام پروکسی‌های API مستقر در تمام محیط‌ها برمی‌گرداند.

از آنجایی که API از نوع RESTful است، می‌توانید به سادگی از متد POST به همراه یک JSON یا XML payload در همان منبع برای ایجاد یک API proxy استفاده کنید.

یک پروفایل برای پروکسی API شما ایجاد می‌شود. نمایش پیش‌فرض یک پروکسی API در قالب نمادگذاری شیء جاوا اسکریپت (JSON) است. در زیر پاسخ پیش‌فرض JSON به درخواست POST بالا آمده است که یک پروکسی API به نام weatherapi ایجاد کرده است. شرح هر عنصر در پروفایل به شرح زیر است:

{
  "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
• APIProxy name : نام منحصر به فرد پروکسی API
• ConfigurationVersion : نسخه سرویس‌های API که پیکربندی پروکسی API با آن مطابقت دارد.
• CreatedAt : زمانی که پروکسی API تولید شده است، با فرمت زمان UNIX
• CreatedBy : آدرس ایمیل کاربر Apigee Edge که پروکسی API را ایجاد کرده است
• DisplayName : یک نام کاربرپسند برای پروکسی API
• LastModifiedAt : زمانی که پروکسی API تولید شده است، با فرمت زمان UNIX
• LastModifiedBy : آدرس ایمیل کاربر Apigee Edge که پروکسی API را ایجاد کرده است.
• Policies : فهرستی از سیاست‌هایی که به این پروکسی API اضافه شده‌اند
• ProxyEndpoints : فهرستی از ProxyEndpointهای نامگذاری‌شده
• Resources : فهرستی از منابع (جاوااسکریپت، پایتون، جاوا، XSLT) که برای اجرا در این پروکسی API در دسترس هستند.
• TargetServers : فهرستی از TargetServersهای نامگذاری‌شده (که می‌توانند با استفاده از API مدیریت ایجاد شوند) که در پیکربندی‌های پیشرفته برای اهداف متعادل‌سازی بار استفاده می‌شوند.
• TargetEndpoints : فهرستی از TargetEndpointهای نامگذاری‌شده

توجه داشته باشید که بسیاری از عناصر پیکربندی پروکسی API که با استفاده از روش ساده POST در بالا ایجاد شده‌اند، خالی هستند. در مباحث بعدی، نحوه افزودن و پیکربندی اجزای کلیدی یک پروکسی API را خواهید آموخت.

همچنین می‌توانید در مورد این عناصر پیکربندی در مرجع پیکربندی پروکسی API مطالعه کنید.

اسکریپت نویسی علیه API

پروکسی‌های API نمونه که در گیت‌هاب موجود هستند، اسکریپت‌های پوسته‌ای ارائه می‌دهند که ابزار استقرار Apigee را در بر می‌گیرند. اگر به هر دلیلی نمی‌توانید از ابزار استقرار پایتون استفاده کنید، می‌توانید مستقیماً API را فراخوانی کنید. هر دو رویکرد در اسکریپت‌های نمونه زیر نشان داده شده‌اند.

بسته‌بندی ابزار استقرار

ابتدا مطمئن شوید که ابزار استقرار پایتون در محیط محلی شما موجود است.

سپس یک فایل برای نگهداری اعتبارنامه‌های خود ایجاد کنید. اسکریپت‌های استقراری که می‌نویسید، این تنظیمات را وارد می‌کنند و به شما کمک می‌کنند تا اعتبارنامه‌های حساب خود را به صورت مرکزی مدیریت کنید. در نمونه 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

فایل بالا تمام تنظیمات شما را در دسترس اسکریپت‌های پوسته‌ای قرار می‌دهد که ابزار استقرار را در بر می‌گیرند.

حالا یک اسکریپت پوسته ایجاد کنید که آن تنظیمات را وارد کند و از آنها برای فراخوانی ابزار استقرار استفاده کند. (برای مثال، به نمونه‌های پلتفرم API Apigee مراجعه کنید.)

#!/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 را خودکار می‌کنند، می‌تواند مفید باشد.

اسکریپت زیر مستقیماً API مدیریت را فراخوانی می‌کند. این اسکریپت، نسخه موجود پروکسی API را که در حال به‌روزرسانی آن هستید، از حالت نصب خارج می‌کند، یک فایل ZIP از دایرکتوری /apiproxy حاوی فایل‌های پیکربندی پروکسی شما ایجاد می‌کند و سپس پیکربندی را آپلود، وارد و نصب می‌کند.

#!/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