بهترین روش ها برای طراحی و توسعه پروکسی API

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

هدف این سند ارائه مجموعه ای از استانداردها و بهترین شیوه ها برای توسعه با Apigee Edge است. موضوعاتی که در اینجا پوشش داده می شوند شامل طراحی، کدگذاری، استفاده از خط مشی، نظارت و اشکال زدایی است. اطلاعات توسط تجربه توسعه دهندگانی که با Apigee کار می کنند برای اجرای برنامه های موفق API جمع آوری شده است. این یک سند زنده است و هر از چند گاهی به روز می شود.

علاوه بر دستورالعمل‌های اینجا، ممکن است پست انجمن آنتی الگوهای Apigee Edge نیز مفید باشد.

استانداردهای توسعه

نظرات و مستندات

  • نظرات درون خطی را در تنظیمات ProxyEndpoint و TargetEndpoint ارائه دهید. نظرات خوانایی یک جریان را افزایش می دهد، به خصوص در مواردی که نام فایل های خط مشی به اندازه کافی توصیفی برای بیان عملکرد اساسی جریان نیستند.
  • نظرات را مفید بیان کنید از اظهار نظرهای آشکار خودداری کنید.
  • از تورفتگی ثابت، فاصله، تراز عمودی و غیره استفاده کنید.

کد نویسی به سبک چارچوب

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

  • برای فعال کردن DRY ("تکرار نکنید")، در صورت امکان، تنظیمات خط مشی و اسکریپت ها باید توابع تخصصی و قابل استفاده مجدد را اجرا کنند. به عنوان مثال، یک سیاست اختصاصی برای استخراج پارامترهای پرس و جو از پیام های درخواست می تواند ExtractVariables.ExtractRequestParameters نامیده شود. یک خط مشی اختصاصی برای تزریق هدرهای CORS را می توان AssignMessage.SetCORSHeaders نامید. سپس می‌توان آن خط‌مشی‌ها را در سیستم کنترل منبع ذخیره کرد و به هر پروکسی API که نیاز به استخراج پارامترها یا تنظیم سرصفحه‌های CORS دارد، اضافه کرد، بدون اینکه نیازی به ایجاد پیکربندی‌های اضافی (و در نتیجه کمتر قابل مدیریت) باشد.
  • خط‌مشی‌ها و منابع استفاده نشده (جاوا اسکریپت، جاوا، XSLT و غیره) را از پراکسی‌های API، به‌ویژه منابع بزرگی که پتانسیل کاهش سرعت واردات و استقرار رویه‌ها را دارند، پاک کنید.

قراردادهای نامگذاری

  • ویژگی Policy name و نام فایل سیاست XML باید یکسان باشند.
  • ویژگی name خط مشی Script و ServiceCallout و نام فایل منبع باید یکسان باشد.
  • DisplayName باید عملکرد خط‌مشی را برای کسی که قبلاً هرگز با آن پراکسی API کار نکرده است، دقیقاً توصیف کند.
  • خط مشی ها را با توجه به عملکرد آنها نامگذاری کنید. Apigee توصیه می کند که یک قرارداد نامگذاری ثابت برای خط مشی های خود ایجاد کنید. به عنوان مثال، از پیشوندهای کوتاه و به دنبال آن دنباله ای از کلمات توصیفی که با خط تیره جدا شده اند استفاده کنید. به عنوان مثال، AM-xxx برای سیاست های AssignMessage. ابزار apigeelint را نیز ببینید.
  • از پسوندهای مناسب برای فایل های منبع، .js برای جاوا اسکریپت، .py برای پایتون و .jar برای فایل های جاوا JAR استفاده کنید.
  • نام متغیرها باید یکسان باشد. اگر سبکی مانند camelCase یا under_score را انتخاب می‌کنید، از آن در سراسر پروکسی API استفاده کنید.
  • در صورت امکان از پیشوندهای متغیر برای سازماندهی متغیرها بر اساس هدف آنها استفاده کنید، برای مثال Consumer.username و Consumer.password .

توسعه پروکسی API

ملاحظات طراحی اولیه

  • برای راهنمایی در مورد طراحی RESTful API، کتاب الکترونیکی Web API Design: The Missing Link را دانلود کنید.
  • تا جایی که ممکن است از سیاست ها و عملکرد Apigee Edge برای ساخت پراکسی های API استفاده کنید. از کدنویسی همه منطق پروکسی در منابع جاوا اسکریپت، جاوا یا پایتون خودداری کنید.
  • جریان ها را به شیوه ای سازمان یافته بسازید. جریان های چندگانه، هر یک با یک شرط، به پیوست های شرطی متعدد به همان PreFlow و Postflow ترجیح داده می شوند.
  • به عنوان یک "failsafe"، یک پروکسی API پیش‌فرض با یک مسیر پایه ProxyEndpoint از / ایجاد کنید. این می تواند برای تغییر مسیر درخواست های API پایه به یک سایت توسعه دهنده، برای بازگرداندن یک پاسخ سفارشی، یا انجام عمل دیگری مفیدتر از بازگرداندن پیش فرض messaging.adaptors.http.flow.ApplicationNotFound استفاده شود.
  • از منابع TargetServer برای جدا کردن پیکربندی های TargetEndpoint از URL های مشخص استفاده کنید و از تبلیغات در محیط ها پشتیبانی کنید.
    به تعادل بار در سرورهای باطن مراجعه کنید.
  • اگر چندین RouteRule دارید، یکی را به‌عنوان «پیش‌فرض» ایجاد کنید، یعنی RouteRule بدون شرط. اطمینان حاصل کنید که RouteRule پیش فرض آخرین بار در لیست Route های شرطی تعریف شده است. RouteRules از بالا به پایین در ProxyEndpoint ارزیابی می شوند.
    مرجع پیکربندی پروکسی API را ببینید.
  • اندازه بسته پروکسی API: بسته های پروکسی API نمی توانند بزرگتر از 15 مگابایت باشند. در Apigee Edge for Private Cloud، می‌توانید محدودیت اندازه را با تغییر ویژگی thrift_framed_transport_size_in_mb در مکان‌های زیر تغییر دهید: cassandra.yaml (در Cassandra) و conf/apigee/management-server/repository.properties.
  • نسخه‌سازی API: برای نظرات و توصیه‌های Apigee در مورد نسخه‌سازی API، به بخش Versioning در طراحی Web API: The Missing Link e-book مراجعه کنید.

فعال کردن CORS

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

CORS (اشتراک‌گذاری منابع متقاطع) مکانیزم استانداردی است که به فراخوان‌های JavaScript XMLHttpRequest (XHR) اجازه می‌دهد تا در یک صفحه وب با منابعی از دامنه‌های غیر اصلی تعامل داشته باشند. CORS راه حلی است که معمولاً برای سیاست یکسانی اجرا می شود که توسط همه مرورگرها اجرا می شود. به عنوان مثال، اگر از طریق اجرای کد جاوا اسکریپت در مرورگر خود، با API توییتر تماس XHR برقرار کنید، تماس با شکست مواجه خواهد شد. این به این دلیل است که دامنه ای که صفحه را به مرورگر شما ارائه می دهد با دامنه ای که به API Twitter سرویس می دهد یکسان نیست. CORS راه حلی برای این مشکل فراهم می کند و به سرورها اجازه می دهد در صورت تمایل به اشتراک گذاری منابع متقاطع، "انتخاب کنند".

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

اندازه محموله پیام

برای جلوگیری از مشکلات حافظه در Edge، اندازه بار پیام به 10 مگابایت محدود شده است. تجاوز از این اندازه ها منجر به خطای 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 0 ارسال کنید.
  • در Edge for Private Cloud نسخه 4.16.01 و بالاتر، ویژگی های زیر را در /opt/apigee/router.properties یا message-processor.properties تنظیم کنید تا محدودیت ها را تغییر دهید. برای اطلاعات بیشتر به تنظیم محدودیت اندازه پیام در روتر یا پردازشگر پیام مراجعه کنید.

    هر دو ویژگی دارای مقدار پیش‌فرض «10m» هستند که مربوط به 10 مگابایت است:
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

رسیدگی به خطا

  • اهرم FaultRules برای رسیدگی به تمام خطاها. (خط مشی های RaiseFault برای توقف جریان پیام و ارسال پردازش به جریان خطاها استفاده می شود.)
  • در جریان خطا، از سیاست‌های AssignMessage برای ایجاد پاسخ خطا استفاده کنید، نه از سیاست‌های RaiseFault. سیاست های AssignMessage را مشروط بر اساس نوع خطای رخ داده اجرا کنید.
  • همیشه شامل یک کنترل‌کننده خطای پیش‌فرض «گیر همه» می‌شود تا خطاهای ایجاد شده توسط سیستم را بتوان به قالب‌های پاسخ خطای تعریف‌شده توسط مشتری نگاشت.
  • در صورت امکان، همیشه پاسخ های خطا را با فرمت های استاندارد موجود در شرکت یا پروژه خود مطابقت دهید.
  • از پیام های خطای معنی دار و قابل خواندن توسط انسان استفاده کنید که راه حلی برای شرایط خطا پیشنهاد می کند.

رسیدگی به عیوب را ببینید.

برای بهترین شیوه‌های صنعت، طراحی پاسخ خطای RESTful را ببینید.

ماندگاری

نقشه های کلید/مقدار

  • از نقشه های کلید/مقدار فقط برای مجموعه داده های محدود استفاده کنید. آنها برای ذخیره اطلاعات بلندمدت طراحی نشده اند.
  • هنگام استفاده از نقشه های کلید/مقدار عملکرد را در نظر بگیرید زیرا این اطلاعات در پایگاه داده Cassandra ذخیره می شود.

به خط مشی عملیات نقشه ارزش کلیدی مراجعه کنید.

ذخیره پاسخ

  • اگر پاسخ موفقیت آمیز نبود یا اگر درخواست GET نیست، کش پاسخ را پر نکنید. موارد ایجاد، به روز رسانی و حذف ها نباید در حافظه پنهان شوند. <SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • حافظه پنهان را با یک نوع محتوای ثابت پر کنید (مثلاً XML یا JSON). پس از بازیابی یک ورودی answerCache، سپس با JSONtoXML یا XMLToJSON به نوع محتوای مورد نیاز تبدیل کنید. این کار از ذخیره سازی داده های مضاعف، سه گانه یا بیشتر جلوگیری می کند.
  • اطمینان حاصل کنید که کلید کش برای نیاز ذخیره کافی است. در بسیاری از موارد، request.querystring می تواند به عنوان شناسه منحصر به فرد استفاده شود.
  • کلید API ( client_id ) را در کلید حافظه پنهان قرار ندهید، مگر اینکه صریحاً لازم باشد. اغلب، APIهایی که فقط با یک کلید ایمن شده اند، داده های یکسانی را برای یک درخواست معین به همه مشتریان باز می گرداند. ذخیره یک مقدار برای تعدادی از ورودی ها بر اساس کلید API ناکارآمد است.
  • برای جلوگیری از خواندن کثیف، فواصل انقضای کش مناسب را تنظیم کنید.
  • هر زمان که ممکن است، سعی کنید سیاست کش پاسخی که کش را پر می کند در پاسخ ProxyEndpoint PostFlow تا جایی که ممکن است دیر اجرا شود. به عبارت دیگر، آن را پس از مراحل ترجمه و میانجیگری، از جمله میانجیگری مبتنی بر جاوا اسکریپت و تبدیل بین JSON و XML اجرا کنید. با ذخیره سازی داده های میانجی، از هزینه عملکرد اجرای مرحله میانجی هر بار که داده های ذخیره شده را بازیابی می کنید، جلوگیری می کنید.

    توجه داشته باشید که اگر میانجیگری منجر به پاسخی متفاوت از درخواست به درخواست شود، ممکن است بخواهید داده های بدون واسطه را در حافظه پنهان ذخیره کنید.

  • سیاست کش پاسخ برای جستجوی ورودی حافظه پنهان باید در درخواست ProxyEndpoint PreFlow رخ دهد. از اجرای منطق بیش از حد، به غیر از تولید کلید حافظه پنهان، قبل از بازگرداندن ورودی حافظه پنهان خودداری کنید. در غیر این صورت، مزایای کش به حداقل می رسد.
  • به طور کلی، همیشه باید جستجوی کش پاسخ را تا حد امکان نزدیک به درخواست مشتری نگه دارید. برعکس، شما باید جمعیت کش پاسخ را تا حد ممکن نزدیک به پاسخ مشتری نگه دارید.
  • هنگام استفاده از چندین خط مشی کش پاسخ متفاوت در یک پروکسی، این دستورالعمل ها را دنبال کنید تا از رفتار گسسته برای هر یک اطمینان حاصل کنید:
    • هر خط مشی را بر اساس شرایط منحصر به فرد متقابل اجرا کنید. این کمک می کند تا اطمینان حاصل شود که تنها یکی از چند سیاست کش پاسخ اجرا می شود.
    • منابع کش مختلف را برای هر خط مشی کش پاسخ تعریف کنید. شما منبع کش را در عنصر <CacheResource> خط مشی مشخص می کنید.

به خط مشی کش پاسخ مراجعه کنید.

خط مشی و کد سفارشی

خط مشی یا کد سفارشی؟

  • قبل از هر چیز (در صورت امکان) از سیاست های داخلی استفاده کنید. سیاست‌های Apigee سخت‌تر، بهینه‌سازی و پشتیبانی می‌شوند. به عنوان مثال، به جای جاوا اسکریپت (در صورت امکان) از سیاست های استاندارد AssignMessage و ExtractVariables برای ایجاد بارگذاری، استخراج اطلاعات از محموله ها (XPath، JSONPath) و غیره استفاده کنید.
  • جاوا اسکریپت بر پایتون و جاوا ترجیح داده می شود. با این حال، اگر عملکرد نیاز اولیه است، جاوا باید از جاوا اسکریپت استفاده شود.

جاوا اسکریپت

  • اگر جاوا اسکریپت بصری تر از سیاست های Apigee است (به عنوان مثال، هنگام تنظیم target.url برای بسیاری از ترکیبات مختلف URI) از جاوا اسکریپت استفاده کنید.
  • تجزیه محموله پیچیده مانند تکرار از طریق یک شی JSON و کدگذاری/رمزگشایی Base64.
  • خط مشی جاوا اسکریپت دارای محدودیت زمانی است، بنابراین حلقه های بی نهایت مسدود می شوند.
  • همیشه از JavaScript Steps استفاده کنید و فایل ها را در پوشه منابع jsc قرار دهید. نوع سیاست جاوا اسکریپت کد را در زمان استقرار از قبل کامپایل می کند.

برنامه نویسی پروکسی های API با جاوا اسکریپت را ببینید.

جاوا

  • اگر عملکرد بالاترین اولویت است، یا اگر منطق در جاوا اسکریپت قابل پیاده سازی نیست، از جاوا استفاده کنید.
  • فایل های منبع جاوا را در ردیابی کد منبع قرار دهید.

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

پایتون

  • از پایتون استفاده نکنید مگر اینکه کاملاً ضروری باشد. اسکریپت‌های پایتون می‌توانند گلوگاه‌های عملکردی را برای اجرای ساده، همانطور که در زمان اجرا تفسیر می‌شوند، معرفی کنند.

فراخوانی اسکریپت (جاوا، جاوا اسکریپت، پایتون)

  • از یک تلاش/گرفتن جهانی یا معادل آن استفاده کنید.
  • استثناهای معنی دار را پرتاب کنید و آنها را به درستی برای استفاده در پاسخ های خطا جمع آوری کنید.
  • استثناها را زودتر پرتاب کنید و بگیرید. برای رسیدگی به همه استثناها از try/catch سراسری استفاده نکنید.
  • در صورت لزوم، بررسی های پوچ و تعریف نشده را انجام دهید. یک مثال از زمان انجام این کار هنگام بازیابی متغیرهای جریان اختیاری است.
  • از انجام درخواست‌های HTTP/S در داخل فراخوانی اسکریپت خودداری کنید. در عوض، از خط مشی Apigee ServiceCallout استفاده کنید، زیرا این خط مشی اتصالات را به خوبی مدیریت می کند.

جاوا اسکریپت

  • جاوا اسکریپت در پلتفرم API از XML از طریق E4X پشتیبانی می کند.

مدل شی جاوا اسکریپت را ببینید.

جاوا

  • هنگام دسترسی به بارهای پیام، سعی کنید از context.getMessage() در مقابل context.getResponseMessage یا context.getRequestMessage استفاده کنید. این تضمین می کند که کد می تواند بار بار را در هر دو جریان درخواست و پاسخ بازیابی کند.
  • کتابخانه ها را به سازمان یا محیط Apigee Edge وارد کنید و آنها را در فایل JAR قرار ندهید. این کار اندازه بسته را کاهش می دهد و به سایر فایل های JAR اجازه می دهد به همان مخزن کتابخانه دسترسی پیدا کنند.
  • فایل های JAR را با استفاده از Apigee resources API وارد کنید نه اینکه آنها را در پوشه منابع پراکسی API وارد کنید. این کار زمان استقرار را کاهش می‌دهد و اجازه می‌دهد همان فایل‌های JAR توسط چندین پراکسی API ارجاع شوند. مزیت دیگر جداسازی کلاس لودر است.
  • از جاوا برای مدیریت منابع (مثلاً ایجاد و مدیریت Thread Pool) استفاده نکنید.

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

پایتون

  • استثناهای معنی دار را پرتاب کنید و آنها را به درستی برای استفاده در پاسخ های خطای Apigee بگیرید

به خط مشی Python Script مراجعه کنید.

ServiceCallouts

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

    اگر بین پراکسی‌هایی که در یک سازمان و محیط هستند وصل می‌شوید، حتماً پروکسی‌های Chaining API را با هم ببینید تا در مورد پیاده‌سازی یک اتصال محلی که از سربار شبکه غیرضروری جلوگیری می‌کند، اطلاعات بیشتری کسب کنید.

  • یک پیام درخواست ServiceCallout با استفاده از خط مشی AssignMessage بسازید و شی درخواست را در متغیر پیام پر کنید. (این شامل تنظیم بار، مسیر و روش درخواست است.)
  • URL که در خط مشی پیکربندی شده است به مشخصات پروتکل نیاز دارد، به این معنی که بخش پروتکل URL، برای مثال https:// ، توسط یک متغیر قابل تعیین نیست. همچنین، باید از متغیرهای جداگانه برای بخش دامنه URL و برای بقیه URL استفاده کنید. به عنوان مثال: https://{domain}/{path}
  • شی پاسخ برای ServiceCallout را در یک متغیر پیام جداگانه ذخیره کنید. سپس می توانید متغیر پیام را تجزیه کنید و بار اصلی پیام را برای استفاده توسط سایر سیاست ها دست نخورده نگه دارید.

به خط مشی Callout Service مراجعه کنید.

دسترسی به نهادها

خط مشی AccessEntity

  • برای عملکرد بهتر، به جای نام برنامه، برنامه ها را بر اساس uuid جستجو کنید.

به خط مشی موجودیت دسترسی مراجعه کنید.

ورود به سیستم

  • از یک سیاست syslog مشترک در بین بسته‌ها و درون همان بسته استفاده کنید. این یک فرمت ثبت یکپارچه را حفظ می کند.

به سیاست MessageLogging مراجعه کنید.

نظارت

مشتریان Cloud ملزم به بررسی اجزای جداگانه Apigee Edge (روترها، پردازشگرهای پیام و غیره) نیستند. تیم عملیات جهانی Apigee با توجه به درخواست‌های بررسی سلامت توسط مشتری، تمام مؤلفه‌ها را به همراه بررسی‌های سلامت API تحت نظر دارد.

Apigee Analytics

تجزیه و تحلیل می تواند نظارت API غیر بحرانی را با اندازه گیری درصد خطا ارائه دهد.

به داشبوردهای Analytics مراجعه کنید.

ردیابی

ابزار ردیابی در رابط کاربری مدیریت API Edge برای اشکال زدایی مشکلات API در زمان اجرا، در طول توسعه یا تولید یک API مفید است.

استفاده از ابزار Trace را ببینید.

امنیت

  • از سیاست های محدودیت آدرس IP برای محدود کردن دسترسی به محیط آزمایشی خود استفاده کنید. اجازه دسترسی به آدرس‌های IP ماشین‌ها یا محیط‌های توسعه‌دهنده خود را بدهید و همه موارد دیگر را ممنوع کنید. خط مشی AccessControl
  • همیشه خط‌مشی‌های حفاظت از محتوا (JSON و یا XML) را برای پراکسی‌های API که برای تولید مستقر می‌شوند، اعمال کنید. خط مشی JSONThreatProtection .
  • برای بهترین شیوه های امنیتی بیشتر به موضوعات زیر مراجعه کنید: