ایجاد پراکسی API از «مشخصات OpenAPI» | Apigee Edge

در این آموزش، با نحوه ایجاد یک پراکسی Edge API از یک «مشخصات» OpenAPI بااستفاده از «میانای کاربری مدیریت Apigee Edge» آشنا می‌شوید. وقتی کارگزار API را با کارخواه HTTP، مثل cURL، فراخوانی می‌کنید، کارگزار API درخواست را به سرویس هدف ساختگی Apigee ارسال می‌کند.

درباره «طرح ابتکاری Open API»

«ابتکار عمل Open API (OAI) بر ایجاد، توسعه، و ترویج «قالب شرح میانای برنامه‌سازی کاربردی» بی‌طرف فروشنده براساس «مشخصات Swagger» تمرکز دارد.» برای کسب اطلاعات بیشتر درباره «طرح ابتکاری Open API»، به https://openapis.org مراجعه کنید.

مشخصات OpenAPI از قالب استانداردی برای توصیف یک RESTful API استفاده می‌کند. «مشخصات OpenAPI» که به قالب JSON یا YAML نوشته شده است، برای ماشین قابل‌خواندن است، اما برای انسان‌ها نیز به‌راحتی قابل‌خواندن و قابل‌درک است. این مشخصات عناصری از میانای برنامه‌سازی کاربردی را مثل مسیر پایه، مسیرها و فعل‌ها، سرایندها، پارامترهای پُرسمان، عملیات، انواع محتوا، شرح‌های پاسخ، و موارد دیگر توصیف می‌کند. علاوه‌براین، از «مشخصات OpenAPI» معمولاً برای تولید مستندات API استفاده می‌شود.

درباره سرویس هدف ساختگی Apigee

سرویس هدف ساختگی Apigee که در این آموزش گام‌به‌گام استفاده می‌شود در Apigee میزبانی می‌شود و داده‌های ساده را برمی‌گرداند. به کلید میانای برنامه‌سازی کاربردی یا کد دسترسی نیاز ندارد. درواقع، می‌توانید در مرورگر وب به آن دسترسی داشته باشید. با کلیک کردن روی موارد زیر، آن را امتحان کنید:

http://mocktarget.apigee.net

سرویس هدف پیام خوشامدگویی Hello, guest! را برمی‌گرداند

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

http://mocktarget.apigee.net/help

آنچه نیاز خواهید داشت

حساب Apigee Edge. اگر حساب ندارید، می‌توانید با دنبال کردن دستورالعمل‌های ایجاد حساب Apigee Edge ثبت‌نام کنید.
مشخصات OpenAPI. در این آموزش گام‌به‌گام، از mocktarget.yaml «مشخصات OpenAPI» استفاده خواهید کرد که سرویس هدف ساختگی Apigee، http://mocktarget.apigee.net، را توصیف می‌کند. برای اطلاعات بیشتر، به https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi مراجعه کنید.
cURL نصب‌شده روی ماشین شما برای برقراری تماس‌های API از خط فرمان؛ یا مرورگر وب.

ایجاد پراکسی میانای برنامه‌سازی کاربردی

Edge

برای ایجاد پراکسی API از «مشخصات OpenAPI» بااستفاده از «واسط کاربر Edge»:

به سیستم https://apigee.com/edge وارد شوید.
در پنجره اصلی، روی «کارگزاران API» کلیک کنید.
یا می‌توانید توسعه > پراکسی‌های API را در نوار پیمایش سمت راست انتخاب کنید.
روی + پراکسی کلیک کنید.
در دستیار «ایجاد پراکسی»، برای الگوی پراکسی معکوس (رایج‌ترین)، روی استفاده از مشخصات OpenAPI کلیک کنید.
روی وارد کردن از نشانی وب کلیک کنید و اطلاعات زیر را وارد کنید:
- نشانی وب مشخصات OpenAPI: مسیر محتوای خام در GitHub برای «مشخصات OpenAPI» در فیلد نشانی وب:
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- نام مشخصات: نام «مشخصات OpenAPI»، مثل هدف ساختگی.
  این نام برای ذخیره کردن «مشخصات OpenAPI» در فروشگاه مشخصات استفاده می‌شود. مدیریت مشخصات را ببینید.

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

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

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

فیلد	شرح	پیش‌فرض
نام	نام پراکسی API. برای مثال: `Mock-Target-API`.	‫`title` دارایی از «مشخصات OpenAPI» با فاصله‌های جایگزین‌شده با خط تیره
مسیر پایه	مؤلفه مسیر که این پراکسی API را به‌طور منحصربه‌فرد در سازمان شناسایی می‌کند. نشانی وب عمومی این پراکسی API از نام سازمان شما، محیطی که این پراکسی API در آن مستقر شده است، و این مسیر پایه تشکیل شده است. برای مثال: `http://myorg-test.apigee.net/mock-target-api`	محتوای فیلد نام به حروف کوچک تبدیل شد
شرح	شرح پراکسی میانای برنامه‌سازی کاربردی.	‫`description` دارایی از «مشخصات OpenAPI»
هدف (میانای برنامه‌سازی کاربردی موجود)	نشانی وب هدف ازطرف این پراکسی API فراخوانده شد. می‌توان از هر نشانی وبی که ازطریق اینترنت باز دردسترس باشد استفاده کرد. برای مثال: `http://mocktarget.apigee.net`	‫`servers` دارایی از «مشخصات OpenAPI»

در زیر گزیده‌ای از «مشخصات OpenAPI» ارائه شده است که دارایی‌هایی را که برای پیش‌پر کردن فیلدها استفاده می‌شوند نشان می‌دهد.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

فیلد توضیحات را به‌صورت زیر ویرایش کنید: API proxy for the Apigee mock target service endpoint.
روی بعدی کلیک کنید.
در صفحه خط‌مشی‌های مشترک، در بخش «امنیت: مجوز»، مطمئن شوید که عبور (بدون مجوز) انتخاب شده باشد و روی بعدی کلیک کنید:
در صفحه «جریان‌ها»، مطمئن شوید که همه عملیات انتخاب شده‌اند.
نکته: جاری‌سازی‌های شرطی به‌طور خودکار از عملکردهایی که در شیء paths در «مشخصات OpenAPI» تعریف شده‌اند تولید می‌شوند. جریان‌های شرطی به Edge می‌گویند: «وقتی این را دیدی، این منطق را اجرا کن.» برای مثال، وقتی فراخوانی API یک GET در منبع /xml (شرط) است، پاسخ را به JSON تبدیل کنید (ازطریق خط‌مشی پیوست‌شده به جریان شرطی). فقط یک جریان در هر تراکنش اجرا می‌شود—اولین جریانی که وضعیت آن به درست ارزیابی می‌شود.
روی بعدی کلیک کنید.
در صفحه میزبان‌های مجازی، پیش‌فرض و امن را انتخاب کنید و روی بعدی کلیک کنید.
در صفحه خلاصه، مطمئن شوید محیط آزمایش در بخش استقرار اختیاری انتخاب شده باشد و روی ایجاد و استقرار کلیک کنید:

‫Apigee پراکسی جدید API شما را ایجاد می‌کند و آن را در محیط آزمایشی‌تان مستقر می‌کند:
برای نمایش صفحه «نمای کلی» برای میانای برنامه‌سازی کاربردی کارگزار، روی ویرایش کارگزار کلیک کنید.

Classic Edge (ابر خصوصی)

برای ایجاد پراکسی API از «مشخصات OpenAPI» بااستفاده از «واسط کاربر Classic Edge»:

به سیستم https://apigee.com/edge وارد شوید.
در پنجره اصلی، روی «کارگزاران API» کلیک کنید.
یا می‌توانید توسعه > پراکسی‌های API را در نوار پیمایش سمت راست انتخاب کنید.
روی + پراکسی کلیک کنید.
در «دستیار ساختن پراکسی»، پراکسی معکوس (رایج‌ترین) را انتخاب کنید و روی استفاده از OpenAPI کلیک کنید.
روی وارد کردن از نشانی وب کلیک کنید، نامی برای «مشخصات OpenAPI» وارد کنید، و مسیر محتوای خام در GitHub را برای «مشخصات OpenAPI» در فیلد نشانی وب وارد کنید:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
روی انتخاب کلیک کنید.

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

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

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

فیلد	شرح	پیش‌فرض
نام پراکسی	نام پراکسی API. برای مثال: `Mock-Target-API`.	‫`title` دارایی از «مشخصات OpenAPI» با فاصله‌های جایگزین‌شده با خط تیره
مسیر پایه پراکسی	مؤلفه مسیر که این پراکسی API را به‌طور منحصربه‌فرد در سازمان شناسایی می‌کند. نشانی وب عمومی این پراکسی API از نام سازمان شما، محیطی که این پراکسی API در آن مستقر شده است، و این مسیر پایه تشکیل شده است. برای مثال: `http://myorg-test.apigee.net/mock-target-api`	محتوای فیلد نام به حروف کوچک تبدیل شد
میانای برنامه‌سازی کاربردی موجود	نشانی وب هدف ازطرف این پراکسی API فراخوانده شد. می‌توان از هر نشانی وبی که ازطریق اینترنت باز دردسترس باشد استفاده کرد. برای مثال: `http://mocktarget.apigee.net`	‫`servers` دارایی از «مشخصات OpenAPI»
شرح	شرح پراکسی میانای برنامه‌سازی کاربردی.	‫`description` دارایی از «مشخصات OpenAPI»

در زیر گزیده‌ای از «مشخصات OpenAPI» ارائه شده است که دارایی‌هایی را که برای پیش‌پر کردن فیلدها استفاده می‌شوند نشان می‌دهد.

openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...

فیلد توضیحات را به‌صورت زیر ویرایش کنید: API proxy for the Apigee mock target service endpoint.
روی بعدی کلیک کنید.
در صفحه «جریان‌ها»، مطمئن شوید که همه عملیات انتخاب شده‌اند.
نکته: جاری‌سازی‌های شرطی به‌طور خودکار از عمل‌هایی که در شیء paths در «مشخصات OpenAPI» تعریف شده‌اند تولید می‌شوند. جریان‌های شرطی به Edge می‌گویند: «وقتی این را دیدی، این منطق را اجرا کن.» برای مثال، وقتی فراخوانی API یک GET در منبع /xml (شرط) است، پاسخ را به JSON تبدیل کنید (ازطریق خط‌مشی پیوست‌شده به جریان شرطی). فقط یک جریان برای هر تراکنش اجرا می‌شود—اولین جریانی که وضعیت آن به درست ارزیابی می‌شود.
روی بعدی کلیک کنید.
در صفحه «امنیت»، عبور (هیچ‌کدام) را به‌عنوان گزینه امنیت انتخاب کنید و روی بعدی کلیک کنید.
در صفحه «میزبانان مجازی»، مطمئن شوید همه میزبانان مجازی انتخاب شده‌اند و روی بعدی کلیک کنید.
در صفحه «ساخت»، مطمئن شوید محیط آزمایش انتخاب شده باشد و روی ساخت و استقرار کلیک کنید.
در صفحه «خلاصه»، تأییدیه‌ای می‌بینید که پراکسی جدید API شما باموفقیت ایجاد شده است و در محیط آزمایش شما مستقر شده است.
روی Mock-Target-API کلیک کنید تا صفحه «نمای کلی» برای پراکسی میانای برنامه‌سازی کاربردی نمایش داده شود.

تبریک! کارگزار نیابتی API را از «مشخصات OpenAPI» ایجاد کرده‌اید. سپس آن را آزمایش می‌کنید تا ببینید چگونه کار می‌کند.

آزمایش پراکسی میانای برنامه‌سازی کاربردی

می‌توانید Mock-Target-API API را بااستفاده از cURL یا مرورگر وب آزمایش کنید.

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

curl http://<org_name>-test.apigee.net/mock-target-api

پاسخ

باید پاسخ زیر را ببینید:

Hello, Guest!

عالی بود! کارگزاری API ساده‌ای را از «مشخصات OpenAPI» ساخته‌اید و آن را آزمایش کرده‌اید.

افزودن خط‌مشی XML به JSON

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

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

curl http://<org_name>-test.apigee.net/mock-target-api/xml

پاسخ

باید پاسخ زیر را ببینید:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

اکنون بیایید کاری انجام دهیم که پاسخ XML را به JSON تبدیل کند. خط‌مشی XML به JSON را به جریان شرطی «مشاهده پاسخ XML» در پراکسی API اضافه کنید.

در گوشه بالا سمت چپ صفحه «نمای کلی» Mock-Target-API در «واسط کاربر Edge»، روی برگه توسعه کلیک کنید.
در قاب «پیمایشگر» سمت راست، در بخش «نقاط پایانی پراکسی» > «پیش‌فرض»، روی جریان شرطی مشاهده پاسخ XML کلیک کنید.
روی دکمه +مرحله پایین، مربوط به پاسخ برای جریان کلیک کنید.

کادر گفتگوی «افزودن مرحله» باز می‌شود تا فهرستی دسته‌بندی‌شده از همه خط‌مشی‌هایی که می‌توانید اضافه کنید نمایش دهد.
به دسته «واسطه‌گری» پیمایش کنید و XML به JSON را انتخاب کنید.
مقادیر پیش‌فرض را برای نام نمایشی و نام حفظ کنید.
روی افزودن کلیک کنید. خط‌مشی تبدیل XML به JSON روی پاسخ اعمال می‌شود.
روی ذخیره کلیک کنید.

اکنون که خط‌مشی را اضافه کرده‌اید، بااستفاده از cURL دوباره با «میانای برنامه‌سازی کاربردی» تماس بگیرید. توجه داشته باشید که همچنان منبع /xml یکسانی را فرا می‌خوانید. سرویس هدف همچنان بلوک XML خود را برمی‌گرداند، اما اکنون خط‌مشی در پراکسی API پاسخ را به JSON تبدیل می‌کند. این تماس را برقرار کن:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

توجه داشته باشید که پاسخ XML به JSON تبدیل می‌شود:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

تبریک! باموفقیت اجرای خط‌مشی اضافه‌شده به جریان شرطی را آزمایش کردید.