شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید . اطلاعات
هر سازمانی یک چرخه حیات توسعه نرم افزار (SDLC) منحصر به فرد دارد. اغلب لازم است که استقرار پروکسی API را با فرآیندهای مورد استفاده برای خدمات باطن همگام سازی و تراز کنید.
روش های Edge API نشان داده شده در این مبحث می توانند برای ادغام مدیریت پروکسی API در SDLC سازمان شما استفاده شوند. استفاده رایج از این API نوشتن اسکریپت ها یا کدهایی است که پراکسی های API را مستقر می کند، یا پروکسی های API را از یک محیط به محیط دیگر منتقل می کند، به عنوان بخشی از یک فرآیند خودکار بزرگتر که همچنین برنامه های کاربردی دیگر را مستقر یا انتقال می دهد.
Edge API هیچ فرضی در مورد SDLC شما (یا هر شخص دیگری در این مورد) ندارد. در عوض، عملکردهای اتمی را نشان می دهد که می تواند توسط تیم توسعه شما هماهنگ شود تا چرخه عمر توسعه API شما را خودکار و بهینه کند.
برای اطلاعات کامل، API های Edge را ببینید.
برای استفاده از Edge API، باید خود را در تماس های خود احراز هویت کنید. می توانید این کار را با یکی از روش های زیر انجام دهید:
- OAuth2 (فقط ابر عمومی)
- SAML (ابر عمومی و خصوصی)
- اعتبار پایه (توصیه نمی شود؛ ابر عمومی و خصوصی)
این مبحث بر مجموعه ای از APIهایی که برای مدیریت پراکسی های API هستند تمرکز دارد.
ویدئو: برای یادگیری نحوه استقرار یک API، این ویدیوی کوتاه را ببینید.
تعامل با API
مراحل زیر شما را از طریق تعاملات ساده با API ها راهنمایی می کند.
APIهای سازمان خود را فهرست کنید
میتوانید با فهرست کردن همه پراکسیهای API در سازمانتان شروع کنید. (به یاد داشته باشید که ورودیهای EMAIL:PASSWORD و ORG_NAME را جایگزین کنید. برای دستورالعملها، به استفاده از Edge API مراجعه کنید.
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 را در محیط prod اجرا کنید، در حالی که همچنان به ایجاد ویرایشهای جدید از آن پراکسی API در محیط آزمایشی ادامه دهید. وقتی آماده شدید، می توانید نسخه بالاتر پروکسی API خود را از محیط آزمایشی نسبت به ویرایش قبلی پروکسی API در محیط prod تبلیغ کنید .
در این مثال، تنها یک ویرایش وجود دارد زیرا پروکسی API به تازگی ایجاد شده است. همانطور که یک پروکسی API در چرخه حیات پیکربندی و استقرار تکراری حرکت می کند، تعداد بازبینی با اعداد صحیح افزایش می یابد. با استفاده از تماسهای مستقیم API برای استقرار، میتوانید به صورت اختیاری شماره ویرایش پراکسی API را افزایش دهید. گاهی اوقات وقتی تغییرات جزئی ایجاد می کنید، ممکن است نخواهید بازبینی را افزایش دهید.
ویرایش API را دریافت کنید
نسخه API (به عنوان مثال، api.company.com/v1
) باید به ندرت تغییر کند. هنگامی که نسخه API را افزایش می دهید، به توسعه دهندگان نشان می دهد که تغییر قابل توجهی در امضای رابط خارجی که توسط API در معرض دید قرار گرفته است، رخ داده است.
ویرایش پروکسی API یک عدد افزایش یافته مرتبط با پیکربندی پروکسی API است. API Services اصلاحاتی را در پیکربندیهای شما انجام میدهد تا زمانی که مشکلی پیش میآید بتوانید پیکربندی را برگردانید. به طور پیشفرض، هر بار که یک پراکسی API را با استفاده از Import an API Proxy API وارد میکنید، بازبینی یک پروکسی API بهطور خودکار افزایش مییابد. اگر نمیخواهید ویرایش یک پروکسی API را افزایش دهید، از آپدیت API پراکسی ویرایش API استفاده کنید. اگر از Maven برای استقرار استفاده میکنید، از گزینههای clean
یا update
استفاده کنید، همانطور که در افزونه Maven readme توضیح داده شده است.
برای مثال، میتوانید روش GET
در API proxy revision 1 فراخوانی کنید تا نمای دقیقی داشته باشید.
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 شما برای دریافت و ارسال درخواست ها به درستی پیکربندی شد، می توانید آن را در یک یا چند محیط مستقر کنید. معمولاً در test
، روی پراکسیهای API تکرار میکنید و پس از آماده شدن، ویرایش پروکسی API را به prod
ارتقا میدهید . اغلب، متوجه میشوید که بازبینیهای بیشتری از یک پروکسی API در محیط آزمایشی دارید، در درجه اول به این دلیل که تکرار بسیار کمتری در محیط prod انجام خواهید داد.
یک پروکسی API تا زمانی که در یک محیط مستقر نشده باشد نمی تواند فراخوانی شود. هنگامی که ویرایش پروکسی API را در prod مستقر کردید، سپس می توانید URL prod
را برای توسعه دهندگان خارجی منتشر کنید.
نحوه فهرست کردن محیط ها
هر سازمانی در Apigee Edge حداقل دو محیط دارد: test
و prod
. تمایز دلخواه است. هدف این است که قبل از اینکه آن را برای توسعه دهندگان خارجی باز کنید، یک منطقه برای تأیید اینکه پروکسی API شما به درستی کار می کند ارائه می کند.
هر محیط در واقع فقط یک آدرس شبکه است که به شما امکان می دهد ترافیک را بین پراکسی های API که روی آن کار می کنید و آنهایی که برنامه ها در زمان اجرا به آنها دسترسی دارند تفکیک کنید.
محیط ها همچنین تفکیک داده ها و منابع را فراهم می کنند. برای مثال میتوانید کشهای مختلفی را در test و prod راهاندازی کنید که فقط توسط پراکسیهای API که در آن محیط اجرا میشوند قابل دسترسی هستند.
مشاهده محیط های یک سازمان
curl -u EMAIL:PASSWORD \ https://api.enterprise.apigee.com/v1/o/ORG_NAME/environments
نمونه پاسخ
[ "test", "prod" ]
استقرارها را کاوش کنید
استقرار بازبینی یک پراکسی API است که در یک محیط مستقر شده است. یک پراکسی API که در حالت مستقر است، از طریق شبکه در آدرسهای تعریف شده در عنصر <VirtualHost>
برای آن محیط قابل دسترسی است.
استقرار پروکسی های API
پراکسی های API تا زمانی که مستقر نشده باشند قابل فراخوانی نیستند. API Services 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
رخ می دهد:
- ویرایش 1 در حال رسیدگی به درخواست ها است.
- نسخه 2 به صورت موازی در حال گسترش است.
- وقتی نسخه 2 به طور کامل اجرا شد، ترافیک جدید به نسخه 2 ارسال می شود. هیچ ترافیک جدیدی به نسخه 1 ارسال نمی شود.
- با این حال، ویرایش 1 ممکن است همچنان تراکنش های موجود را پردازش کند. با تنظیم پارامتر
delay
(مثلاً 15 ثانیه)، به ویرایش 1 15 ثانیه فرصت می دهید تا پردازش تراکنش های موجود را به پایان برساند. - پس از فاصله زمانی تاخیر، نسخه 1 از کار افتاده است.
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 | پیشفرض برای نادیده گرفتن رفتار استقرار عادی و ارائه استقرار یکپارچه، روی |
delay | برای اینکه اجازه دهید پردازش تراکنش در نسخه موجود قبل از اجرا نشدن کامل شود - و احتمال خطاهای پیش فرض 0 (صفر) ثانیه است. وقتی |
هنگامی که override=true
همراه با delay
استفاده می شود، پاسخ های HTTP 5XX
در طول استقرار حذف می شوند. این به این دلیل است که هر دو ویرایش پروکسی API به طور همزمان اجرا میشوند و نسخه قدیمیتر پس از تأخیر اجرا نمیشود.
تمام استقرارهای یک ویرایش API را ببینید
گاهی اوقات لازم است فهرستی از تمام ویرایشهای موجود در یک پروکسی 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 در یک محیط مستقر شده است.
همه استقرارها را در محیط آزمایش مشاهده کنید
همچنین میتوانید وضعیت استقرار را برای یک محیط خاص (از جمله شماره ویرایش پروکسی 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، در برابر همان منبع برای ایجاد یک پراکسی API استفاده کنید.
نمایه ای برای پروکسی 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 Services نگهداری میشود -
APIProxy name
: نام منحصر به فرد پروکسی API -
ConfigurationVersion
: نسخه خدمات API که پیکربندی پروکسی API با آن مطابقت دارد -
CreatedAt
: زمانی که پروکسی API تولید شد و در زمان یونیکس فرمت شد -
CreatedBy
: آدرس ایمیل کاربر Apigee Edge که پروکسی API را ایجاد کرده است -
DisplayName
: یک نام کاربرپسند برای پراکسی API -
LastModifiedAt
: زمان ایجاد پراکسی API، فرمت شده در زمان یونیکس -
LastModifiedBy
: آدرس ایمیل کاربر Apigee Edge که پروکسی API را ایجاد کرده است. -
Policies
: فهرستی از خطمشیهایی که به این پراکسی API اضافه شدهاند -
ProxyEndpoints
: فهرستی از ProxyEndpoints با نام -
Resources
: فهرستی از منابع (جاوا اسکریپت، پایتون، جاوا، XSLT) در دسترس برای اجرا در این پراکسی API -
TargetServers
: لیستی از TargetServers با نام (که می تواند با استفاده از API مدیریت ایجاد شود)، که در پیکربندی های پیشرفته برای اهداف متعادل سازی بار استفاده می شود. -
TargetEndpoints
: لیستی از TargetEndpoints با نام
توجه داشته باشید که بسیاری از عناصر پیکربندی پروکسی API ایجاد شده با استفاده از روش ساده POST
در بالا خالی هستند. در مباحث زیر، نحوه افزودن و پیکربندی اجزای کلیدی یک پروکسی API را خواهید آموخت.
همچنین میتوانید در مورد این عناصر پیکربندی در مرجع پیکربندی پروکسی API مطالعه کنید.
اسکریپت در برابر API
استفاده از نمونه پراکسی های API موجود در GitHub اسکریپت های پوسته ای را ارائه می دهد که ابزار استقرار Apigee را می پوشاند. اگر به دلایلی نمی توانید از ابزار توسعه پایتون استفاده کنید، می توانید مستقیماً با API تماس بگیرید. هر دو رویکرد در اسکریپتهای نمونه زیر نشان داده شدهاند.
بسته بندی ابزار Deploy
ابتدا مطمئن شوید که ابزار توسعه پایتون در محیط محلی شما موجود است.
سپس یک فایل برای نگهداری اطلاعات خود بسازید. اسکریپتهای استقراری که مینویسید، این تنظیمات را وارد میکنند و به شما کمک میکنند اعتبارنامههای حسابتان را بهطور مرکزی مدیریت کنید. در نمونه پلتفرم API، این فایل 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
فایل بالا تمام تنظیمات شما را در دسترس اسکریپت های پوسته ای قرار می دهد که ابزار استقرار را می پوشانند.
اکنون یک اسکریپت پوسته ایجاد کنید که آن تنظیمات را وارد کرده و از آنها برای فراخوانی ابزار Deploy استفاده می کند. (برای مثال به نمونه های پلت فرم Apigee API مراجعه کنید.)
#!/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