درحال مشاهده اسناد Apigee Edge هستید.
به
اسناد Apigee X بروید. اطلاعات
هدف این سند ارائه مجموعهای از استانداردها و روالهای مطلوب برای توسعه با Apigee Edge است. موضوعاتی که در اینجا پوشش داده میشوند شامل طراحی، کدنویسی، استفاده از خطمشی، نظارت، و اشکالزدایی است. این اطلاعات از تجربه توسعهدهندگانی که با Apigee کار کردهاند جمعآوری شده است تا برنامههای موفق API را پیادهسازی کنند. این سندی پویا است و هرچند وقت یکبار بهروز خواهد شد.
علاوهبر رهنمودهای اینجا، ممکن است پست انجمن الگوهای ضد Apigee Edge را نیز مفید بدانید.
استانداردهای توسعه
نظرات و مستندات
- نظرات درونخطی را در پیکربندیهای ProxyEndpoint و TargetEndpoint ارائه دهید. نظرات خوانایی «جریان» را بهبود میبخشد، بهویژه در مواردی که نام فایل خطمشی بهاندازه کافی توصیفی نیست تا عملکرد زیربنایی «جریان» را بیان کند.
- نظرات مفید ارائه دهید. از نظرات بدیهی اجتناب کنید.
- از تورفتگی، فاصلهگذاری، تراز عمودی، و غیره یکسان استفاده کنید.
کدنویسی سبک چارچوب
کدنویسی به سبک چارچوب شامل ذخیره کردن منابع پراکسی API در سیستم کنترل نسخه خودتان برای استفاده مجدد در محیطهای توسعه محلی است. برای مثال، برای استفاده مجدد از خطمشی، آن را در کنترل منبع ذخیره کنید تا توسعهدهندگان بتوانند آن را همگامسازی کنند و در محیطهای توسعه پراکسی خودشان از آن استفاده کنند.
- برای فعال کردن DRY («خودتان را تکرار نکنید»)، درصورت امکان، پیکربندیهای خطمشی و اسکریپتها باید عملکردهای تخصصی و قابلاستفاده مجدد را پیادهسازی کنند. برای مثال، خطمشی اختصاصی برای استخراج
پارامترهای پُرسمان از پیامهای درخواست میتواند
ExtractVariables.ExtractRequestParametersنامیده شود. خطمشی اختصاصی برای تزریق سرایندهای CORS میتواندAssignMessage.SetCORSHeadersنامیده شود. سپس میتوانید این خطمشیها را در سیستم کنترل منبع خود ذخیره کنید و به هر پراکسی API که نیاز به استخراج پارامترها یا تنظیم سرایندهای CORS دارد اضافه کنید، بدون اینکه نیاز باشد پیکربندیهای اضافی (و در نتیجه کمتر قابل مدیریت) ایجاد کنید. - خطمشیها و منابع استفادهنشده (جاوا اسکریپت، جاوا، XSLT، و غیره) را از پراکسیهای API پاکسازی کنید، بهویژه منابع بزرگی که میتوانند فرایندهای وارد کردن و استقرار را کند کنند.
قراردادهای نامگذاری
- مشخصه «خطمشی»
nameو نام فایل خطمشی XML باید یکسان باشند. - ویژگی خطمشی «نوشتار» و «برنمای تماس با خدمات»
nameو نام فایل منبع باید یکسان باشد. DisplayNameباید عملکرد خطمشی را برای کسی که قبلاً با آن پراکسی API کار نکرده است بهدرستی شرح دهد.- خطمشیها را براساس عملکردشان نامگذاری کنید. Apigee توصیه میکند که برای خطمشیهایتان قرارداد نامگذاری یکسانی ایجاد کنید.
برای مثال، از پیشوندهای کوتاه استفاده کنید و پساز آن مجموعهای از کلمات توصیفی را با خط تیره از هم جدا کنید. برای مثال،
AM-xxxبرای خطمشیهای «اختصاص پیام». همچنین ابزار apigeelint را ببینید. - از پسوندهای مناسب برای فایلهای منبع،
.jsبرای جاوا اسکریپت،.pyبرای پایتون، و.jarبرای فایلهای Java JAR استفاده کنید. - نامهای متغیر باید یکسان باشد. اگر سبکی را انتخاب میکنید، مثلاً camelCase یا under_score، در سراسر پراکسی API از آن استفاده کنید.
- درصورت امکان، از پیشوندهای متغیر برای سازماندهی متغیرها براساس هدف آنها استفاده کنید، برای مثال،
Consumer.usernameوConsumer.password.
توسعه پراکسی میانای برنامهسازی کاربردی
ملاحظات اولیه طراحی
- برای دریافت راهنمایی درباره طراحی «میانای برنامهسازی کاربردی» سازگار با REST، کتاب الکترونیکی Web API Design: The Missing Link را بارگیری کنید.
- تا جایی که ممکن است از خطمشیها و عملکرد Apigee Edge برای ساختن پراکسیهای API استفاده کنید. از کدنویسی کردن همه منطق کارگزار نیابتی در منابع جاوا اسکریپت، جاوا، یا پایتون خودداری کنید.
- جریانها را بهشیوهای سازمانیافته بسازید. چندین جریان که هرکدام یک شرط دارند به چندین پیوست شرطی به همان «جریان پیشاز اجرا» و «جریان پساز اجرا» ترجیح داده میشوند.
- بهعنوان «تدبیر احتیاطی»، یک پراکسی API پیشفرض با ProxyEndpoint BasePath از
/ایجاد کنید. از این ویژگی میتوان برای هدایت درخواستهای پایه API به سایت توسعهدهنده، برای برگرداندن پاسخ سفارشی، یا انجام کنشی دیگر که مفیدتر از برگرداندنmessaging.adaptors.http.flow.ApplicationNotFoundپیشفرض است استفاده کرد.
- از منابع TargetServer برای جدا کردن پیکربندیهای TargetEndpoint از نشانیهای وب عینی استفاده کنید و
از ارتقا در محیطهای مختلف پشتیبانی کنید.
توزیع بار در سرورهای زیرینه را ببینید. - اگر چند RouteRule دارید، یکی را بهعنوان «پیشفرض» ایجاد کنید، یعنی بهعنوان RouteRule بدون شرط. مطمئن شوید که «قانون مسیر» پیشفرض در انتهای فهرست «مسیرهای» شرطی تعریف شده باشد. RouteRules در ProxyEndpoint از بالا به پایین ارزیابی میشوند.
مرجع پیکربندی پراکسی میانای برنامهسازی کاربردی را ببینید. - اندازه دسته پراکسی API: دستههای پراکسی API نمیتوانند بزرگتر از ۱۵ مگابایت باشند. در Apigee Edge for
Private Cloud، میتوانید با تغییر دادن
دارایی
thrift_framed_transport_size_in_mbدر مکانهای زیر، محدودیت اندازه را تغییر دهید: cassandra.yaml (در Cassandra) و conf/apigee/management-server/repository.properties. - نسخهبندی میانای برنامهسازی کاربردی: برای دیدگاهها و توصیههای Apigee درباره نسخهبندی میانای برنامهسازی کاربردی، بخش «نسخهبندی» را در کتاب الکترونیکی طراحی میانای برنامهسازی کاربردی وب: حلقه گمشده ببینید.
فعال کردن CORS
قبلاز انتشار میاناهای برنامهسازی کاربردی، باید CORS را در پراکسیهای میانای برنامهسازی کاربردی خود فعال کنید تا از درخواستهای مبدأ متقاطع سمت کارخواه پشتیبانی کنید.
CORS (همرسانی منبع میانمبدئی) سازوکار استانداردی است که به فراخوانیهای JavaScript XMLHttpRequest (XHR) اجراشده در صفحه وب اجازه میدهد با منابع دامنههای غیرمبدأ تعامل داشته باشد. CORS راهحلی است که معمولاً برای خطمشی مبدأ یکسان که توسط همه مرورگرها اعمال میشود پیادهسازی میشود. برای مثال، اگر از کد JavaScript درحال اجرا در مرورگرتان، فراخوانی XHR به Twitter API انجام دهید، فراخوانی ناموفق خواهد بود. دلیل این امر این است که دامنهای که صفحه را به مرورگر شما ارائه میدهد با دامنهای که Twitter API را ارائه میدهد یکسان نیست. CORS با اجازه دادن به سرورها برای «موافقت» با همرسانی منابع مبدأ متقاطع، راهحلی برای این مشکل ارائه میدهد.
برای کسب اطلاعات درباره فعال کردن CORS در پراکسیهای میانای برنامهسازی کاربردی قبلاز انتشار میاناهای برنامهسازی کاربردی، به افزودن پشتیبانی CORS به پراکسی میانای برنامهسازی کاربردی مراجعه کنید.
اندازه پایهبار پیام
برای جلوگیری از مشکلات حافظه در Edge، اندازه پایهبار پیام به ۱۰ مگابایت محدود شده است. فرا رفتن از این
اندازهها منجر به خطای protocol.http.TooBigBody میشود.
این مشکل در این پست «انجمن Apigee» نیز مورد بحث قرار گرفته است.
استراتژیهای توصیهشده برای مدیریت اندازههای بزرگ پیام در Edge در زیر آمده است:
- درخواستها و پاسخها را جاریسازی کنید. توجه داشته باشید که وقتی جاریسازی میکنید، خطمشیها دیگر به محتوای پیام دسترسی ندارند. درخواستها و پاسخهای «جاریسازی» را ببینید.
- در Edge for Private Cloud نسخه 4.15.07 و نسخههای قدیمیتر، فایل
http.propertiesپردازشگر پیام را ویرایش کنید تا محدودیت را در پارامترHTTPResponse.body.buffer.limitافزایش دهید. حتماً قبلاز استقرار تغییر در تولید، آن را آزمایش کنید. -
در Edge for Private Cloud نسخه 4.16.01 و نسخههای جدیدتر، درخواستهای دارای بار باید شامل سرایند «Content-Length» یا درصورت جاریسازی، سرایند «Transfer-Encoding: chunked» باشد. برای POST به پراکسی API با بار خالی، باید Content-Length را روی ۰ تنظیم کنید.
- در Edge for Private Cloud نسخه 4.16.01 و نسخههای جدیدتر، ویژگیهای زیر را در
/opt/apigee/router.properties یا message-processor.properties تنظیم کنید تا محدودیتها را تغییر دهید. برای اطلاعات بیشتر،
محدودیت اندازه پیام را در «مسیریاب» یا «پردازشگر پیام» تنظیم کنید.
هر دو دارایی مقدار پیشفرض «۱۰ دقیقه» دارند که معادل ۱۰ مگابایت است:-
conf_http_HTTPRequest.body.buffer.limit
-
conf_http_HTTPResponse.body.buffer.limit
-
مدیریت خطا
- از FaultRules برای مدیریت همه مدیریت خطا استفاده کنید. (از خطمشیهای RaiseFault برای متوقف کردن «جریان پیام» و ارسال پردازش به «جریان FaultRules» استفاده میشود.)
- در «جریان FaultRules»، از خطمشیهای «AssignMessage» برای ساختن پاسخ خطا استفاده کنید، نه خطمشیهای «RaiseFault». خطمشیهای «اختصاص پیام» را براساس نوع خطایی که رخ میدهد بهصورت شرطی اجرا کنید.
- همیشه شامل یک کنترلکننده خطای پیشفرض «همه» است تا خطاهای تولیدشده توسط سیستم بتوانند به قالبهای پاسخ خطای تعریفشده توسط مشتری نگاشت شوند.
- درصورت امکان، همیشه پاسخهای خطا را با هر قالب استانداردی که در شرکت یا پروژه شما دردسترس است مطابقت دهید.
- از پیامهای خطای معنادار و قابلخواندن برای انسان استفاده کنید که راهحلی برای وضعیت خطا پیشنهاد میدهد.
رسیدگی به خطاها را ببینید.
برای روالهای مطلوب صنعت، طراحی پاسخ خطای RESTfulرا ببینید.
ماندگاری
نقشههای کلید/مقدار
- از نقشههای کلید/مقدار فقط برای مجموعههای داده محدود استفاده کنید. این سیستمها برای ذخیرهسازی بلندمدت دادهها طراحی نشدهاند.
- هنگام استفاده از نقشههای کلید/مقدار، عملکرد را درنظر بگیرید زیرا این اطلاعات در پایگاه داده Cassandra ذخیره میشود.
خطمشی عملیات نقشه مقدار کلید را ببینید.
ذخیره کردن پاسخ در حافظه نهان
- اگر پاسخ موفقیتآمیز نبود یا اگر درخواست GET نبود، حافظه نهان پاسخ را تکمیل نکنید. ایجاد، بهروزرسانی، و حذف نباید در حافظه نهان ذخیره شود.
<SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation> - حافظه نهان را با یک نوع محتوای سازگار (برای مثال، XML یا JSON) پر کنید. پساز بازیابی ورودی responseCache، سپس با JSONtoXML یا XMLToJSON به نوع محتوای موردنیاز تبدیل کنید. این کار از ذخیره شدن دادههای دوبرابر، سهبرابر، یا بیشتر جلوگیری میکند.
- مطمئن شوید که کلید حافظه نهان برای نیاز حافظه نهان کافی است. در بسیاری از موارد،
request.querystringمیتواند بهعنوان شناسه یکتا استفاده شود. - کلید میانای برنامهسازی کاربردی (
client_id) را در کلید حافظه نهان قرار ندهید، مگراینکه بهطور صریح الزامی باشد. اغلب، میاناهای برنامهسازی کاربردی که فقط با کلید ایمن شدهاند، دادههای یکسانی را برای همه مشتریان برای یک درخواست معین برمیگردانند. ذخیره کردن مقدار یکسان برای تعدادی ورودی براساس کلید میانای برنامهسازی کاربردی غیرمؤثر است. - برای جلوگیری از خواندنهای کثیف، فواصل انقضای مناسب برای حافظه نهان تنظیم کنید.
- هرگاه ممکن بود، سعی کنید خطمشی حافظه نهان پاسخ که حافظه نهان را پر میکند
در پاسخ ProxyEndpoint در PostFlow تا حد امکان دیر اجرا شود. بهعبارت دیگر، آن را پساز مراحل ترجمه و میانجیگری، ازجمله میانجیگری مبتنی بر جاوا اسکریپت و تبدیل بین JSON و XML اجرا کنید. با ذخیره کردن دادههای واسطهای در حافظه نهان، از هزینه عملکرد اجرای مرحله واسطهگری هر بار که دادههای ذخیرهشده در حافظه نهان را بازیابی میکنید، جلوگیری میکنید.
توجه داشته باشید که اگر میانجیگری منجر به پاسخ متفاوتی از درخواست به درخواست شود، ممکن است بخواهید بهجای آن دادههای بدون میانجیگری را در حافظه نهان ذخیره کنید.
- خطمشی حافظه نهان پاسخ برای جستجوی ورودی حافظه نهان باید در درخواست PreFlow در ProxyEndpoint رخ دهد. از پیادهسازی منطق بیشازحد، بهجز تولید کلید حافظه نهان، قبلاز برگرداندن ورودی حافظه نهان خودداری کنید. درغیراینصورت، مزایای ذخیره در حافظه نهان به حداقل میرسد.
- بهطورکلی، همیشه باید جستجوی حافظه نهان پاسخ را تا حد امکان نزدیک به درخواست مشتری نگه دارید. برعکس، باید جمعیت حافظه نهان پاسخ را تا حد امکان نزدیک به پاسخ مشتری نگه دارید.
- هنگام استفاده از چندین خطمشی متفاوت حافظه نهان پاسخ در یک پراکسی، این دستورالعملها را دنبال کنید
تا از رفتار مجزای هرکدام مطمئن شوید:
- هر خطمشی را براساس شرایط متقابلاً انحصاری اجرا کنید. این کار کمک میکند مطمئن شوید فقط یکی از چند خطمشی حافظه نهان پاسخ اجرا میشود.
- برای هر خطمشی حافظه نهان پاسخ، منابع حافظه نهان متفاوتی تعریف کنید. منبع حافظه نهان را در عنصر <CacheResource> خطمشی مشخص میکنید.
خطمشی «پاسخ نهانگاه» را ببینید.
خطمشی و کد سفارشی
خطمشی یا کد سفارشی؟
- ابتدا و مهمتر از همه از خطمشیهای داخلی استفاده کنید (درصورت امکان). خطمشیهای Apigee تقویتشده، بهینهسازیشده، و پشتیبانیشده هستند. برای مثال، از خطمشیهای استاندارد AssignMessage و ExtractVariables بهجای JavaScript (درصورت امکان) برای ایجاد بار، استخراج اطلاعات از بار (XPath، JSONPath)، و غیره استفاده کنید.
- جاوا اسکریپت بر Python و Java ترجیح داده میشود. بااینحال، اگر عملکرد اولویت اصلی باشد، باید از Java بهجای JavaScript استفاده شود.
JavaScript
- اگر استفاده از جاوا اسکریپت نسبت به خطمشیهای Apigee شهودیتر است (برای مثال، هنگام تنظیم
target.urlبرای ترکیبهای مختلف نشانی وب)، از جاوا اسکریپت استفاده کنید. - تجزیه بار پیچیده مانند تکرار ازطریق شیء JSON و کدبندی/رمزگشایی Base64.
- خطمشی جاوااسکریپت دارای محدودیت زمانی است، بنابراین حلقههای بینهایت مسدود میشوند.
- همیشه از «مراحل جاوا اسکریپت» استفاده کنید و فایلها را در پوشه منابع
jscقرار دهید. نوع «خطمشی جاوا اسکریپت» کد را در زمان استقرار ازپیش کامپایل میکند.
پراکسیهای میانای برنامهسازی کاربردی برنامهنویسی با جاوا اسکریپت را ببینید.
جاوا
- اگر عملکرد بالاترین اولویت است یا اگر منطق را نمیتوان در جاوا اسکریپت پیادهسازی کرد، از جاوا استفاده کنید.
- فایلهای منبع Java را در ردیابی کد منبع بگنجانید.
برای کسب اطلاعات درباره استفاده از Java در پراکسیهای API، به تبدیل پاسخ به حروف بزرگ با یک فراخوانی Java و خطمشی فراخوانی Java مراجعه کنید.
Python
- مگر در موارد کاملاً ضروری از Python استفاده نکنید. اسکریپتهای Python میتوانند برای اجراهای ساده گلوگاههای عملکردی ایجاد کنند، زیرا در زمان اجرا تفسیر میشوند.
نوشتههای راهنمای دستورگان (Java، JavaScript، Python)
- از try/catch جهانی یا معادل آن استفاده کنید.
- استثناهای معنادار ایجاد کنید و آنها را بهدرستی برای استفاده در پاسخهای خطا دریافت کنید.
- استثناها را زودتر درنظر بگیرید و مدیریت کنید. از try/catch سراسری برای مدیریت همه استثناها استفاده نکنید.
- درصورت نیاز، بررسیهای null و undefined را انجام دهید. مثالی از زمان انجام این کار، هنگام بازیابی متغیرهای جریان اختیاری است.
- از ایجاد درخواستهای HTTP/S در داخل یک نوشته راهنمای دستورگان خودداری کنید. درعوض، از خطمشی Apigee ServiceCallout استفاده کنید زیرا این خطمشی اتصالات را بهطور مناسب مدیریت میکند.
JavaScript
- «جاوا اسکریپت» در «پلاتفرم API» از XML ازطریق E4X پشتیبانی میکند.
مدل شیء جاوا اسکریپت را ببینید.
جاوا
- هنگام دسترسی به محتوای پیام، سعی کنید از
context.getMessage()دربرابرcontext.getResponseMessageیاcontext.getRequestMessageاستفاده کنید. این کار تضمین میکند که کد میتواند محتوا را در هر دو جریان درخواست و پاسخ بازیابی کند. - کتابخانهها را به سازمان یا محیط Apigee Edge وارد کنید و آنها را در فایل JAR قرار ندهید. این کار اندازه دستهبندی را کاهش میدهد و به فایلهای JAR دیگر اجازه میدهد به مخزن کتابخانه یکسانی دسترسی داشته باشند.
- فایلهای JAR را بااستفاده از «میانای برنامهسازی کاربردی» منابع Apigee درونبرد کنید، نه اینکه آنها را در پوشه منابع پراکسی «میانای برنامهسازی کاربردی» قرار دهید. این کار زمانهای استقرار را کاهش میدهد و به فایلهای JAR یکسان اجازه میدهد توسط چندین پراکسی API ارجاع داده شوند. مزیت دیگر، جداسازی بارکننده کلاس است.
- از Java برای مدیریت منابع (برای مثال، ایجاد و مدیریت استخرهای رشته) استفاده نکنید.
تبدیل پاسخ به حروف بزرگ با یک فراخوانی Java را ببینید.
Python
- استثناهای معنادار ایجاد کنید و آنها را بهدرستی برای استفاده در پاسخهای خطای Apigee دریافت کنید
خطمشی «دستورگان Python» را ببینید.
ServiceCallouts
- موارد استفاده معتبر زیادی برای استفاده از زنجیره پراکسی وجود دارد، جایی که از یک فراخوانی سرویس در
یک پراکسی API برای فراخوانی پراکسی API دیگر استفاده میکنید. اگر از زنجیره پراکسی استفاده میکنید، حتماً از
فراخوانیهای بازگشتی «حلقه بینهایت» به همان پراکسی API اجتناب کنید.
اگر بین پراکسیهایی که در یک سازمان و محیط هستند اتصال برقرار میکنید، حتماً زنجیر کردن پراکسیهای API با هم را برای اطلاعات بیشتر درباره پیادهسازی اتصال محلی که از سربار شبکه غیرضروری جلوگیری میکند ببینید.
- پیام درخواست ServiceCallout را بااستفاده از خطمشی AssignMessage بسازید و شیء درخواست را در متغیر پیام تکمیل کنید. (این شامل تنظیم کردن بار درخواست، مسیر، و روش میشود.)
- نشانی وبی که در خطمشی پیکربندی شده است به مشخصه پروتکل نیاز دارد، یعنی
بخش پروتکل نشانی وب، برای مثال
https://، نمیتواند با متغیر مشخص شود. همچنین، باید از متغیرهای جداگانه برای بخش دامنه نشانی وب و برای بقیه نشانی وب استفاده کنید. برای مثال:https://{domain}/{path} - شیء پاسخ را برای «تماس با سرویس» در متغیر پیام جداگانهای ذخیره کنید. سپس میتوانید متغیر پیام را تجزیه کنید و بار پیام اصلی را برای استفاده توسط خطمشیهای دیگر دستنخورده نگه دارید.
خطمشی «نوشته راهنمای تماس با خدمات» را ببینید.
دسترسی به نهادها
خطمشی AccessEntity
- برای عملکرد بهتر، برنامهها را بهجای نام برنامه براساس
uuidجستجو کنید.
خطمشی «دسترسی به نهاد» را ببینید.
ثبت
- از خطمشی syslog مشترک در سراسر دستهها و در یک دسته استفاده کنید. با این کار، قالب گزارشگیری یکنواخت حفظ خواهد شد.
خطمشی MessageLogging را ببینید.
پایش کردن
مشتریان Cloud ملزم به بررسی تکتک عناصر Apigee Edge (مسیریابها، پردازشگران پیام، و غیره) نیستند. تیم «عملیات جهانی» Apigee همه عناصر را بههمراه بررسیهای سلامت API بهطور کامل پایش میکند و درخواستهای بررسی سلامت را از مشتری دریافت میکند.
Apigee Analytics
Analytics میتواند نظارت غیرحیاتی بر API را ارائه دهد زیرا درصد خطاها اندازهگیری میشود.
داشبوردهای Analytics را ببینید.
ردیابی
ابزار ردیابی در واسط کاربر مدیریت API Edge برای اشکالزدایی مشکلات API زمان اجرا درطول توسعه یا عملیات تولید API مفید است.
استفاده از ابزار ردیابی را ببینید.
امنیت
- از خطمشیهای محدودیت نشانی IP برای محدود کردن دسترسی به محیط آزمایش استفاده کنید. دسترسی را برای نشانیهای IP ماشینها یا محیطهای توسعهتان مجاز کنید و دسترسی همه موارد دیگر را غیرمجاز کنید. خطمشی AccessControl.
- همیشه خطمشیهای محافظت از محتوا (JSON و یا XML) را برای پراکسیهای API که در تولید مستقر شدهاند اعمال کنید. خطمشی JSONThreatProtection.
- برای اطلاع از روالهای مطلوب امنیتی بیشتر، موضوعات زیر را ببینید: