مشخصات asyncapi

بخشی از این محتوا از کارهای بزرگی که مردمی در ابتکار عمل OpenAPI انجام داده اند ، گرفته شده است. عمدتا به این دلیل که این یک کار عالی است و ما می خواهیم تا حد امکان سازگاری را با مشخصات OpenAPI حفظ کنیم.

نسخه 2. 0. 0

کلمات کلیدی "باید" ، "نباید" ، "مورد نیاز" ، "باید" ، "نباید" ، "باید" ، "نباید" ، "توصیه شده" ، "ممکن است" و "اختیاری" در این سندبرای تفسیر همانطور که در RFC 2119 شرح داده شده است. مشخصات Asyncapi تحت مجوز Apache ، نسخه 2. 0 مجوز دارد.

معرفی

مشخصات Asyncapi یک پروژه است که برای توصیف و مستند سازی API های پیام محور در یک قالب قابل خواندن با دستگاه استفاده می شود. این پروتکل-آگنوستیک است ، بنابراین می توانید از آن برای API هایی که بر روی هر پروتکل کار می کنند استفاده کنید (به عنوان مثال ، AMQP ، MQTT ، WebSockets ، Kafka ، Stomp ، HTTP و غیره). مشخصات Asyncapi مجموعه ای از پرونده های مورد نیاز برای توصیف چنین API را تعریف می کند. سپس از این پرونده ها می توان برای ایجاد برنامه های کاربردی مانند اسناد ، ادغام و/یا ابزار تست استفاده کرد. پرونده (ها) باید عملیاتی را که یک برنامه می پذیرد توصیف کند. به عنوان مثال ، قطعه تعریف زیر asyncapi زیر را در نظر بگیرید:

1 2 3 کاربر/امضا شده:   اشتراک در:  ref ref: "#/مؤلفه ها/پیام ها/کاربران "

این بدان معناست که این برنامه به مصرف کنندگان اجازه می دهد تا در کانال کاربر/Signedup مشترک شوند تا پیام های کاربران را دریافت کنند. مشخصات Asyncapi هیچ نوع توپولوژی ، معماری یا الگوی نرم افزاری را فرض نمی کند. بنابراین ، یک سرور ممکن است یک کارگزار پیام ، یک سرور وب یا هر نوع برنامه رایانه ای باشد که قادر به ارسال و/یا دریافت داده باشد. با این حال ، Asyncapi مکانیسمی به نام "اتصالات" را ارائه می دهد که هدف آن کمک به اطلاعات خاص تر در مورد پروتکل و/یا توپولوژی است.

تعاریف

کاربرد

یک برنامه هر نوع برنامه رایانه ای یا گروهی از آنهاست. این باید یک تولید کننده ، مصرف کننده یا هر دو باشد. یک برنامه ممکن است یک میکروسرویس ، دستگاه IoT (سنسور) ، فرآیند اصلی و غیره باشد. یک برنامه ممکن است تا زمانی که از پروتکل انتخاب شده پشتیبانی کند ، در هر تعداد از زبان برنامه نویسی مختلف نوشته شود. یک برنامه همچنین باید از پروتکل پشتیبانی شده توسط سرور برای اتصال و تبادل پیام استفاده کند.

تهيه كننده

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

مصرف كننده

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

پیام

پیام مکانیسمی است که توسط آن اطلاعات از طریق کانال بین سرورها و برنامه ها رد و بدل می شود. یک پیام باید حاوی یک بار باشد و همچنین ممکن است حاوی هدر باشد. این هدرها ممکن است به عنوان های تعریف شده توسط پروتکل و خصوصیات هدر تعریف شده توسط برنامه تقسیم شوند که می تواند به عنوان ابرداده پشتیبانی شود. Payload شامل داده هایی است که توسط برنامه تعریف شده است ، که باید به یک قالب (JSON ، XML ، AVRO ، باینری و غیره) سریال شود. از آنجا که یک پیام یک مکانیسم عمومی است ، می تواند از الگوهای تعامل چندگانه مانند رویداد ، فرمان ، درخواست یا پاسخ پشتیبانی کند.

کانال

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

پروتکل

پروتکل مکانیسم (پروتکل سیم یا API) است که توسط آن پیام ها بین برنامه و کانال رد و بدل می شوند. پروتکل مثال شامل ، اما محدود به AMQP ، HTTP ، JMS ، KAFKA ، MQTT ، Stomp ، WebSocket نیست.

مشخصات

قالب

پرونده هایی که API پیام محور را مطابق با مشخصات ASYNCAPI توصیف می کنند ، به عنوان اشیاء JSON نشان داده شده و مطابق با استانداردهای JSON هستند. YAML ، به عنوان یک سوپراست JSON ، می تواند از یک پرونده A2S (مشخصات Asyncapi) نیز استفاده شود. به عنوان مثال ، اگر گفته می شود یک زمینه دارای مقدار آرایه ای است ، از نمایش آرایه JSON استفاده می شود:

1 2 3   "رشته" : [. ]  >

• برچسب ها باید محدود به موارد مجاز توسط قوانین JSON Schema باشند
• کلیدهای مورد استفاده در نقشه های YAML باید به یک رشته مقیاس محدود شوند ، همانطور که توسط YAML Failsafe Schema تعریف شده است

ساختار پرونده

نمایندگی A2S از API از یک پرونده واحد ساخته شده است. با این حال ، بخش هایی از تعاریف را می توان با اختیار کاربر به پرونده های جداگانه تقسیم کرد. این برای زمینه های ref $ در مشخصات به شرح زیر از تعاریف طرحواره JSON قابل اجرا است.

طبق کنوانسیون ، پرونده مشخصات Asyncapi (A2S) نامگذاری شده است Asyncapi. json یا Asyncapi. yaml.

طرح

شیء asyncapi

این شیء سند اصلی برای مشخصات API است. این لیست منابع و اعلامیه API را با هم در یک سند ترکیب می کند.

زمینه های ثابت

این شی را می توان با پسوندهای مشخصات گسترش داد.

رشته نسخه asyncapi

رشته نسخه نسخه مشخصات Asyncapi را که این سند از آن پیروی می کند ، نشان می دهد. قالب این رشته باید عمده باشد. جزئی . پچاین پچ ممکن است توسط یک شخصیت های مختلف و الفبای اضافی پسوند باشد.

عمده . جزئی برای تعیین نسخه مشخصات Asyncapi استفاده می شود و با مشخصات Asyncapi مشخص شده توسط آن عمده سازگار خواهد بود. نسخه جزئی. نسخه پچ با ابزار در نظر گرفته نمی شود و هیچ تمایزی بین 1. 0. 0 و 1. 0. 1 ایجاد نمی شود.

در نسخه های بعدی از مشخصات Asyncapi ، مراقبت به گونه ای داده می شود که افزایش نسخه جزئی نباید در عملکرد ابزار ایجاد شده به نسخه جزئی پایین تر تداخل داشته باشد. بنابراین مشخصات فرضی 1. 1. 0 باید با ابزار طراحی شده برای 1. 0. 0 قابل استفاده باشد.

مشخص کننده

این قسمت یک شناسه جهانی منحصر به فرد از برنامه ای است که سند Asyncapi در حال تعریف است. مطابق با RFC3986 ، باید مطابق با فرمت URI باشد.

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

مثال ها

1 2 3   "شناسه": "U: com: SmartyLighting: Streetlights: Server" >