شما در حال مشاهده مستندات Apigee Edge هستید.
به مستندات Apigee X مراجعه کنید . اطلاعات
بخشهای بعدی شما را با محصولات API و مفاهیم کلیدی مرتبط آشنا میکنند.
محصول API چیست؟
به عنوان یک ارائه دهنده API، شما محصولات API ایجاد میکنید تا APIهای خود را بستهبندی کرده و آنها را برای مصرف در اختیار توسعهدهندگان برنامه قرار دهید. میتوانید محصولات API را به عنوان خط تولید خود در نظر بگیرید.
به طور خاص، یک محصول API موارد زیر را در کنار هم قرار میدهد:
- جمعآوری منابع API (URI)
- طرح خدمات
- فرادادههای مختص کسب و کار شما برای نظارت یا تجزیه و تحلیل (اختیاری)
منابع API موجود در یک محصول API میتوانند از یک یا چند API تهیه شوند، بنابراین میتوانید منابع را با هم ترکیب و تطبیق دهید تا مجموعه ویژگیهای تخصصی ایجاد کنید، همانطور که در شکل زیر نشان داده شده است.
شما میتوانید چندین محصول API ایجاد کنید تا موارد استفادهای را که نیازهای خاصی را برطرف میکنند، برطرف کنید. به عنوان مثال، میتوانید یک محصول API ایجاد کنید که تعدادی از منابع نقشهبرداری را در خود جای داده است تا توسعهدهندگان بتوانند به راحتی نقشهها را در برنامههای خود ادغام کنند. علاوه بر این، میتوانید ویژگیهای مختلفی را برای هر محصول API تنظیم کنید، مانند سطوح قیمتگذاری مختلف. به عنوان مثال، میتوانید ترکیبات محصول API زیر را ارائه دهید:
- یک محصول API که محدودیت دسترسی پایینی، مانند ۱۰۰۰ درخواست در روز، را با قیمت مناسب ارائه میدهد. یک محصول API دوم که دسترسی به همان منابع را فراهم میکند، اما با محدودیت دسترسی بالاتر و قیمت بالاتر.
- یک محصول API رایگان که دسترسی فقط خواندنی به منابع را ارائه میدهد. یک محصول API دوم که دسترسی خواندن/نوشتن به همان منابع را با هزینهای اندک فراهم میکند.
علاوه بر این، میتوانید دسترسی به منابع API را در یک محصول API کنترل کنید. به عنوان مثال، میتوانید منابعی را که فقط توسط توسعهدهندگان داخلی یا فقط توسط مشتریان پولی قابل دسترسی هستند، دستهبندی کنید.
محصولات API مکانیزم مرکزی برای مجوزدهی و کنترل دسترسی به APIهای شما هستند. در Apigee، کلیدهای API نه برای خود APIها، بلکه برای محصولات API ارائه میشوند. به عبارت دیگر، کلیدهای API برای بستههایی از منابع با یک طرح سرویس متصل ارائه میشوند.
توسعهدهندگان برنامه با ثبت برنامههای خود، همانطور که در ثبت برنامهها توضیح داده شده است، به محصولات API شما دسترسی پیدا میکنند. هنگامی که یک برنامه سعی در دسترسی به یک محصول API دارد، مجوز توسط Apigee در زمان اجرا اعمال میشود تا اطمینان حاصل شود که:
- برنامه درخواستکننده مجاز به دسترسی به یک منبع API خاص است.
- برنامه درخواست کننده از سهمیه مجاز تجاوز نکرده است.
- در صورت تعریف، محدودههای OAuth تعریفشده در محصول API با محدودههای مرتبط با توکن دسترسی ارائهشده توسط برنامه مطابقت دارند.
درک مفاهیم کلیدی
قبل از ایجاد محصولات API خود، مفاهیم کلیدی زیر را مرور کنید.
کلیدهای API
وقتی یک برنامه توسعهدهنده را در سازمان خود ثبت میکنید، برنامه باید حداقل با یک محصول API مرتبط باشد. در نتیجه جفت شدن یک برنامه با یک یا چند محصول API، Edge یک کلید مصرفکننده منحصر به فرد به برنامه اختصاص میدهد.
کلید مصرفکننده یا توکن دسترسی به عنوان اعتبارنامه درخواست عمل میکنند. توسعهدهنده برنامه، کلید مصرفکننده را در برنامه جاسازی میکند، به طوری که وقتی برنامه درخواستی را به یک API میزبانی شده توسط Edge ارسال میکند، برنامه کلید مصرفکننده را در درخواست به یکی از روشهای زیر ارسال میکند:
- وقتی API از تأیید کلید API استفاده میکند، برنامه باید کلید مصرفکننده را مستقیماً ارسال کند.
- وقتی API از تأیید توکن OAuth استفاده میکند، برنامه باید توکنی را که از کلید مصرفکننده مشتق شده است، ارسال کند.
اجرای کلید API به طور خودکار اتفاق نمیافتد. چه از کلید مصرفکننده استفاده شود و چه از توکنهای OAuth به عنوان اعتبارنامه درخواست، API Proxy اعتبارنامههای درخواست را در پروکسیهای API شما با گنجاندن یک سیاست VerifyAPIKey یا یک سیاست OAuth/VerifyAccessToken در جریان مناسب، اعتبارسنجی میکند. اگر سیاست اجرای اعتبارنامه را در پروکسی API خود لحاظ نکنید، هر تماسگیرندهای میتواند APIهای شما را فراخوانی کند. برای اطلاعات بیشتر، به سیاست Verify API Key مراجعه کنید.
برای تأیید اعتبارنامههای ارسالی در درخواست، Edge مراحل زیر را انجام میدهد:
- اعتبارنامههایی را که با درخواست ارسال میشوند، دریافت کنید. در مورد تأیید توکن OAuth، Edge تأیید میکند که توکن منقضی نشده باشد و سپس کلید مصرفی که برای تولید توکن استفاده شده است را جستجو میکند.
- فهرست محصولات API که کلید مصرفکننده به آنها مرتبط شده است را بازیابی کنید.
- تأیید کنید که پروکسی API فعلی در محصول API گنجانده شده است، و آیا مسیر منبع فعلی (مسیر URL) در محصول API فعال است یا خیر.
- تأیید کنید که کلید مصرفکننده منقضی یا باطل نشده باشد، بررسی کنید که برنامه باطل نشده باشد و بررسی کنید که توسعهدهنده برنامه فعال باشد.
اگر تمام بررسیهای فوق با موفقیت انجام شود، تأیید اعتبار با موفقیت انجام میشود.
در نهایت، اج به طور خودکار کلیدهای مصرفکننده را تولید میکند، اما ناشران API باید با استفاده از سیاستهای مناسب، بررسی کلید را در پروکسیهای API اعمال کنند.
تأیید خودکار در مقابل تأیید دستی
به طور پیشفرض، تمام درخواستهای دریافت کلید برای دسترسی به یک محصول API از یک برنامه به طور خودکار تأیید میشوند. به عنوان یک جایگزین، میتوانید محصول API را طوری پیکربندی کنید که کلیدها را به صورت دستی تأیید کند. در این حالت، باید درخواستهای کلید را از هر برنامهای که محصول API را اضافه میکند، تأیید کنید. برای اطلاعات بیشتر، به ثبت برنامهها و مدیریت کلیدهای API مراجعه کنید.
سهمیهها
سهمیهها میتوانند از سرورهای بکاند شما در برابر ترافیک بالا محافظت کنند و خط تولید شما را متمایز کنند. به عنوان مثال، ممکن است بخواهید منابع را با سهمیه بالا به عنوان یک محصول پریمیوم بستهبندی کنید و از همان بسته با سهمیه پایینتر به عنوان یک محصول پایه استفاده کنید. سهمیه میتواند به محافظت از سرورهای شما در برابر ازدحام در صورتی که یک محصول محبوب باشد و درخواستهای زیادی دریافت کند، کمک کند.
برای اطلاعات بیشتر در مورد پیکربندی سهمیه، به سیاست سهمیهبندی مراجعه کنید. برای اطلاعات بیشتر در مورد استفاده از تنظیمات سهمیهبندی محصول در سیاستهای سهمیهبندی، به مقاله انجمن زیر مراجعه کنید : چگونه تنظیمات سهمیهبندی روی یک محصول API با سیاستهای سهمیهبندی در یک پروکسی API تعامل دارند؟
دامنههای OAuth
به عنوان یک سطح امنیتی اضافه، میتوانید هر محدوده OAuth را به صورت یک لیست جدا شده با کاما تعریف کنید که باید در توکنهای دسترسی ارسال شده از طریق محصول وجود داشته باشد. هنگام ایجاد یک محصول، باید از تمام محدودههایی که سازمان شما استفاده میکند آگاه باشید. محدودههایی که به یک محصول اضافه میکنید باید با محدودههای موجود مطابقت داشته باشند، در غیر این صورت محصول امن نیست.
برای اطلاعات بیشتر در مورد استفاده از محدودهها با سیاستهای Edge OAuth، به بخش «کار با محدودههای OAuth2» مراجعه کنید.
سطوح دسترسی
هنگام تعریف یک محصول API، میتوانید سطوح دسترسی زیر را تنظیم کنید.
| سطح دسترسی | توضیحات |
|---|---|
| عمومی | محصولات API که برای همه توسعهدهندگان در دسترس هستند. میتوانید آنها را به پورتالهای توسعهدهندگان یکپارچه یا مبتنی بر دروپال اضافه کنید. |
| فقط خصوصی یا داخلی | محصولات API که برای استفاده خصوصی یا داخلی طراحی شدهاند. توجه: هیچ تفاوت عملکردی بین سطوح دسترسی Private و Internal only وجود ندارد. برچسبی را انتخاب کنید که به بهترین شکل مخاطب مورد نظر محصول API را توصیف کند. برای پورتال یکپارچه، میتوانید محصولات API خصوصی یا داخلی را اضافه کنید و در صورت نیاز، آنها را در دسترس توسعهدهندگان برنامه قرار دهید. برای پورتالهای توسعهدهندگان مبتنی بر دروپال، میتوانید دسترسی به محصولات API خصوصی یا داخلی را در پورتال توسعهدهندگان خود مدیریت کنید، همانطور که در بخشهای زیر توضیح داده شده است:
|
درک مفاهیم کلیدی
قبل از ایجاد محصولات API خود، مفاهیم کلیدی زیر را مرور کنید.
کلیدهای API
وقتی یک برنامه توسعهدهنده را در سازمان خود ثبت میکنید، برنامه باید حداقل با یک محصول API مرتبط باشد. در نتیجه جفت شدن یک برنامه با یک یا چند محصول API، Edge یک کلید مصرفکننده منحصر به فرد به برنامه اختصاص میدهد.
کلید مصرفکننده یا توکن دسترسی به عنوان اعتبارنامه درخواست عمل میکنند. توسعهدهنده برنامه، کلید مصرفکننده را در برنامه جاسازی میکند، به طوری که وقتی برنامه درخواستی را به یک API میزبانی شده توسط Edge ارسال میکند، برنامه کلید مصرفکننده را در درخواست به یکی از روشهای زیر ارسال میکند:
- وقتی API از تأیید کلید API استفاده میکند، برنامه باید کلید مصرفکننده را مستقیماً ارسال کند.
- وقتی API از تأیید توکن OAuth استفاده میکند، برنامه باید توکنی را که از کلید مصرفکننده مشتق شده است، ارسال کند.
اجرای کلید API به طور خودکار اتفاق نمیافتد. چه از کلید مصرفکننده استفاده شود و چه از توکنهای OAuth به عنوان اعتبارنامه درخواست، API Proxy اعتبارنامههای درخواست را در پروکسیهای API شما با گنجاندن یک سیاست VerifyAPIKey یا یک سیاست OAuth/VerifyAccessToken در جریان مناسب، اعتبارسنجی میکند. اگر سیاست اجرای اعتبارنامه را در پروکسی API خود لحاظ نکنید، هر تماسگیرندهای میتواند APIهای شما را فراخوانی کند. برای اطلاعات بیشتر، به سیاست Verify API Key مراجعه کنید.
برای تأیید اعتبارنامههای ارسالی در درخواست، Edge مراحل زیر را انجام میدهد:
- اعتبارنامههایی را که با درخواست ارسال میشوند، دریافت کنید. در مورد تأیید توکن OAuth، Edge تأیید میکند که توکن منقضی نشده باشد و سپس کلید مصرفی که برای تولید توکن استفاده شده است را جستجو میکند.
- فهرست محصولات API که کلید مصرفکننده به آنها مرتبط شده است را بازیابی کنید.
- تأیید کنید که پروکسی API فعلی در محصول API گنجانده شده است، و آیا مسیر منبع فعلی (مسیر URL) در محصول API فعال است یا خیر.
- تأیید کنید که کلید مصرفکننده منقضی یا باطل نشده باشد، بررسی کنید که برنامه باطل نشده باشد و بررسی کنید که توسعهدهنده برنامه فعال باشد.
اگر تمام بررسیهای فوق با موفقیت انجام شود، تأیید اعتبار با موفقیت انجام میشود.
در نهایت، اج به طور خودکار کلیدهای مصرفکننده را تولید میکند، اما ناشران API باید با استفاده از سیاستهای مناسب، بررسی کلید را در پروکسیهای API اعمال کنند.
تأیید خودکار در مقابل تأیید دستی
به طور پیشفرض، تمام درخواستهای دریافت کلید برای دسترسی به یک محصول API از یک برنامه به طور خودکار تأیید میشوند. به عنوان یک جایگزین، میتوانید محصول API را طوری پیکربندی کنید که کلیدها را به صورت دستی تأیید کند. در این حالت، باید درخواستهای کلید را از هر برنامهای که محصول API را اضافه میکند، تأیید کنید. برای اطلاعات بیشتر، به ثبت برنامهها و مدیریت کلیدهای API مراجعه کنید.
سهمیهها
سهمیهها میتوانند از سرورهای بکاند شما در برابر ترافیک بالا محافظت کنند و خط تولید شما را متمایز کنند. به عنوان مثال، ممکن است بخواهید منابع را با سهمیه بالا به عنوان یک محصول پریمیوم بستهبندی کنید و از همان بسته با سهمیه پایینتر به عنوان یک محصول پایه استفاده کنید. سهمیه میتواند به محافظت از سرورهای شما در برابر ازدحام در صورتی که یک محصول محبوب باشد و درخواستهای زیادی دریافت کند، کمک کند.
برای اطلاعات بیشتر در مورد پیکربندی سهمیه، به سیاست سهمیهبندی مراجعه کنید. برای اطلاعات بیشتر در مورد استفاده از تنظیمات سهمیهبندی محصول در سیاستهای سهمیهبندی، به مقاله انجمن زیر مراجعه کنید : چگونه تنظیمات سهمیهبندی روی یک محصول API با سیاستهای سهمیهبندی در یک پروکسی API تعامل دارند؟
دامنههای OAuth
به عنوان یک سطح امنیتی اضافه، میتوانید هر محدوده OAuth را به صورت یک لیست جدا شده با کاما تعریف کنید که باید در توکنهای دسترسی ارسال شده از طریق محصول وجود داشته باشد. هنگام ایجاد یک محصول، باید از تمام محدودههایی که سازمان شما استفاده میکند آگاه باشید. محدودههایی که به یک محصول اضافه میکنید باید با محدودههای موجود مطابقت داشته باشند، در غیر این صورت محصول امن نیست.
برای اطلاعات بیشتر در مورد استفاده از محدودهها با سیاستهای Edge OAuth، به بخش «کار با محدودههای OAuth2» مراجعه کنید.
سطوح دسترسی
هنگام تعریف یک محصول API، میتوانید سطوح دسترسی زیر را تنظیم کنید.
| سطح دسترسی | توضیحات |
|---|---|
| عمومی | محصولات API که برای همه توسعهدهندگان در دسترس هستند. میتوانید آنها را به پورتالهای توسعهدهندگان یکپارچه یا مبتنی بر دروپال اضافه کنید. |
| فقط خصوصی یا داخلی | محصولات API که برای استفاده خصوصی یا داخلی طراحی شدهاند. توجه: هیچ تفاوت عملکردی بین سطوح دسترسی Private و Internal only وجود ندارد. برچسبی را انتخاب کنید که به بهترین شکل مخاطب مورد نظر محصول API را توصیف کند. برای پورتال یکپارچه، میتوانید محصولات API خصوصی یا داخلی را اضافه کنید و در صورت نیاز، آنها را در دسترس توسعهدهندگان برنامه قرار دهید. برای پورتالهای توسعهدهندگان مبتنی بر دروپال، میتوانید دسترسی به محصولات API خصوصی یا داخلی را در پورتال توسعهدهندگان خود مدیریت کنید، همانطور که در بخشهای زیر توضیح داده شده است:
|