API های خود را منتشر کنید (نسخه اصلی)

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

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

مروری بر انتشار API

فرآیند انتشار APIها در پورتال شما یک فرآیند دو مرحله‌ای است:

1. محصول API مورد نظر خود را برای انتشار در پورتال خود انتخاب کنید.
2. به طور خودکار مستندات مرجع API را از یک snapshot از مشخصات OpenAPI خود ایجاد کنید تا توسعه‌دهندگان برنامه بتوانند در مورد APIهای شما اطلاعات کسب کنند. (برای اطلاعات بیشتر در مورد snapshotها، به snapshot از مشخصات OpenAPI چیست؟ مراجعه کنید.)

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

• یک صفحه مرجع API به پورتال شما اضافه می‌شود.
  صفحه مرجع API، مستندات مرجع API را که شما به طور خودکار از یک تصویر لحظه‌ای از مشخصات OpenAPI خود ایجاد می‌کنید، نمایش می‌دهد. توسعه‌دهندگان می‌توانند مستندات API شما را بررسی کرده و برای ارسال درخواست API و مشاهده خروجی، روی «امتحان کن» کلیک کنند.

  توجه : شما نمی‌توانید محتوای این صفحه را مستقیماً ویرایش کنید؛ این صفحه در فهرست صفحات پورتال شما نمایش داده نمی‌شود.

  

• پیوندی به صفحه مرجع API به صفحه APIها اضافه شده است
  صفحه APIها (که در پورتال نمونه موجود است) فهرستی از تمام APIهای منتشر شده در پورتال شما را به همراه لینک‌هایی به مستندات مرجع API مربوطه برای اطلاعات بیشتر ارائه می‌دهد.

  توجه : شما نمی‌توانید محتوای این صفحه را مستقیماً ویرایش کنید؛ این صفحه در فهرست صفحات پورتال شما نمایش داده نمی‌شود.

  

خلاصه‌ای از مشخصات OpenAPI چیست؟

هر مشخصات OpenAPI به عنوان منبع حقیقت در طول چرخه حیات یک API عمل می‌کند. همان مشخصات در هر مرحله از چرخه حیات API، از توسعه گرفته تا انتشار و نظارت، استفاده می‌شود. هنگامی که یک مشخصات را تغییر می‌دهید، باید از تأثیر تغییرات بر API خود در سایر مراحل چرخه حیات آگاه باشید، همانطور که در بخش «اگر یک مشخصات را تغییر دهم چه اتفاقی می‌افتد؟» توضیح داده شده است.

وقتی API خود را منتشر می‌کنید، از مشخصات OpenAPI یک snapshot می‌گیرید تا مستندات مرجع API را ایجاد کنید. آن snapshot نشان دهنده یک نسخه خاص از مشخصات در مخزن مشخصات است. اگر مشخصات OpenAPI را با استفاده از ویرایشگر مشخصات تغییر دهید، ممکن است تصمیم بگیرید که یک snapshot دیگر از مشخصات بگیرید تا آخرین تغییرات را در مستندات مرجع API منعکس کنید.

افزودن پشتیبانی CORS به پروکسی‌های API شما

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

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

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

توجه : اکثر مرورگرهای مدرن CORS را اجرا می‌کنند. لیست جامع مرورگرهای پشتیبانی شده را مرور کنید. برای شرح مفصلی از CORS، به توصیه W3C در مورد اشتراک منابع Cross-Origin مراجعه کنید.

صفحه APIها را کاوش کنید

برای دسترسی به صفحه APIها:

1. انتشار > پورتال‌ها را انتخاب کنید و پورتال خود را انتخاب کنید.
2. در صفحه اصلی پورتال، روی APIها کلیک کنید.

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

لیست APIها نمایش داده می‌شود.

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

• جزئیات API های موجود در پورتال خود را مشاهده کنید
• یک API به پورتال خود اضافه کنید
• برای به‌روزرسانی مستندات مرجع API ، از مشخصات OpenAPI مرتبط با یک محصول API، یک تصویر لحظه‌ای تهیه کنید.
• انتشار یا عدم انتشار یک API در پورتال شما
• مخاطبان API را در پورتال خود مدیریت کنید
• مشخصات مرتبط را ویرایش کنید ( به ایجاد مشخصات با استفاده از ویرایشگر مشخصات مراجعه کنید)
• حذف یک API از پورتال شما
• به سرعت APIهای «یتیم» که محصول API مرتبط با آنها از Edge حذف شده است را شناسایی کنید و محصول API را دوباره ایجاد کنید یا API را از پورتال خود حذف کنید.

یک API به پورتال خود اضافه کنید

توجه : شما می‌توانید حداکثر ۱۰۰ API به پورتال خود اضافه کنید.

برای افزودن API به پورتال خود:

1. انتشار > پورتال‌ها را انتخاب کنید و پورتال خود را انتخاب کنید.
2. در صفحه اصلی پورتال، روی APIها کلیک کنید.
   از طرف دیگر، می‌توانید APIها را در منوی کشویی پورتال در نوار پیمایش بالا انتخاب کنید.
3. روی + API کلیک کنید.
   پنجره‌ی «افزودن محصول API به پورتال» نمایش داده می‌شود.

4. در تب محصول API در پنجره‌ی محاوره‌ای، محصول API مورد نظر برای اضافه کردن به پورتال خود را انتخاب کنید.
   

5. روی بعدی کلیک کنید.

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

   از طرف دیگر، می‌توانید انتخاب کنید:

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

7. برای انتشار API در پورتال خود، کادر انتخاب «منتشر شده» را علامت بزنید. اگر آماده انتشار API نیستید، گزینه «منتشر شده» را از حالت انتخاب خارج کنید.
   می‌توانید تنظیمات را بعداً تغییر دهید، همانطور که در بخش انتشار یا لغو انتشار API در پورتال شما توضیح داده شده است.

8. در قسمت مخاطبان، یکی از گزینه‌های زیر را برای مدیریت مخاطبان API خود با اجازه دسترسی به موارد زیر انتخاب کنید:

   • کاربران ناشناس برای اینکه به همه کاربران اجازه مشاهده صفحه را بدهند.
   • کاربران ثبت‌نام‌شده تا فقط کاربران ثبت‌نام‌شده بتوانند صفحه را مشاهده کنند.

   می‌توانید تنظیمات را بعداً، همانطور که در مدیریت مخاطبان API در پورتال شما توضیح داده شده است، تغییر دهید.

9. روی پایان کلیک کنید.

از مشخصات عکس بگیرید

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

برای گرفتن تصویری از مشخصات OpenAPI:

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

4. کلیک .

   نکته : اگر snapshot شما با مشخصات منبع انتخاب شده، به‌روز باشد، پیامی نمایش داده می‌شود.

5. یکی از مشخصات موجود را از منوی کشویی Snapshot Source انتخاب کنید یا برای انتخاب، گزینه Choose a different spec را انتخاب کنید یا مشخصات جدیدی را برای استفاده در تولید مستندات API آپلود کنید. همچنین می‌توانید برای حذف مشخصات فعلی، گزینه No spec را انتخاب کنید.

6. روی به‌روزرسانی اسنپ‌شات (یا اگر بدون مشخصات (No Spec) را انتخاب کرده‌اید، روی حذف اسنپ‌شات ) کلیک کنید.

مستندات مرجع API از مشخصات تولید شده و به صفحه مرجع API اضافه می‌شود.

انتشار یا عدم انتشار یک API در پورتال شما

برای انتشار یا عدم انتشار یک API در پورتال خود:

1. انتشار > پورتال‌ها را انتخاب کنید و پورتال خود را انتخاب کنید.
2. در صفحه اصلی پورتال، روی APIها کلیک کنید.
   از طرف دیگر، می‌توانید APIها را در منوی کشویی پورتال در نوار پیمایش بالا انتخاب کنید.
3. مکان‌نما را روی API که می‌خواهید منتشر یا لغو انتشار کنید، قرار دهید.
4. کلیک .
5. برای انتشار API در پورتال خود، کادر انتخاب «فعال» را علامت بزنید. برای لغو انتشار API، کادر انتخاب «فعال» را بردارید.
6. روی ذخیره کلیک کنید.

مخاطبان API را در پورتال خود مدیریت کنید

مخاطبان API خود را در پورتال خود با اجازه دسترسی به موارد زیر مدیریت کنید:

• همه کاربران
• فقط کاربران ثبت نام شده

برای مدیریت مخاطبان برای API در پورتال خود:

1. انتشار > پورتال‌ها را انتخاب کنید و پورتال خود را انتخاب کنید.
2. در صفحه اصلی پورتال، روی APIها کلیک کنید.
   از طرف دیگر، می‌توانید APIها را در منوی کشویی پورتال در نوار پیمایش بالا انتخاب کنید.
3. مکان‌نما را روی API که می‌خواهید مخاطبان آن را مدیریت کنید، قرار دهید تا اقدامات نمایش داده شوند.
4. کلیک .
5. در قسمت مخاطبان، یکی از گزینه‌های زیر را انتخاب کنید:
   • کاربران ناشناس برای اینکه به همه کاربران اجازه مشاهده محصول API را بدهند.
   • کاربران ثبت‌نام‌شده تا فقط کاربران ثبت‌نام‌شده بتوانند محصول API را مشاهده کنند.
6. روی ذخیره کلیک کنید.

حذف یک API از پورتال شما

برای حذف یک API از پورتال خود:

1. انتشار > پورتال‌ها را انتخاب کنید و پورتال خود را انتخاب کنید.
2. در صفحه اصلی پورتال، روی APIها کلیک کنید.
   از طرف دیگر، می‌توانید APIها را در منوی کشویی پورتال در نوار پیمایش بالا انتخاب کنید.
3. برای نمایش منوی اقدامات، مکان‌نما را روی API موجود در لیست قرار دهید.
4. کلیک .

عیب‌یابی مشکلات مربوط به APIهای منتشر شده شما

هنگام استفاده از Try It، اگر TypeError: Failed to fetch برگردانده شد، دلایل و راه‌حل‌های احتمالی زیر را در نظر بگیرید:

• برای خطاهای محتوای ترکیبی، ممکن است خطا ناشی از یک مشکل شناخته‌شده در swagger-ui باشد. یک راه حل ممکن این است که مطمئن شوید HTTPS را قبل از HTTP در تعریف schemes در مشخصات OpenAPI خود مشخص کرده‌اید. برای مثال:

   schemes:
     - https
     - http
  

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