ניהול מוצרי API

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

מוצרי API מאגדים את ממשקי ה-API שלכם ומאפשרים למפתחי אפליקציות להשתמש בהם. סקירה כללית של מוצרי API מופיעה במאמר מהו מוצר API?

סקירה של דף הסקירה הכללית של מוצרי ה-API

בדף הסקירה הכללית Products מוצגים כל מוצרי ה-API שלכם ופרטים מסוימים לגבי כל אחד מהם. בדף הזה אפשר ליצור מוצר API חדש, למחוק מוצר או לבחור מוצר כדי לראות או לערוך אותו.

כדי לגשת לדף הסקירה הכללית של Products במסוף Cloud ב-Apigee:

לדף API products

בממשק המשתמש של Products אפשר לבצע את המשימות הנפוצות הבאות:

הפעולות האלה מתוארות בפירוט בסעיפים הבאים.

יצירת מוצר API

בקטע הזה מוסבר איך ליצור מוצר API באמצעות ממשקי המשתמש של Apigee.

כדי ליצור מוצר API באמצעות ממשק המשתמש של Apigee:

  1. עוברים לדף הסקירה הכללית של Apigee > Products:

    לדף API products

  2. לוחצים על ‎+ Create. מוצג דף הגדרת המוצר.
  3. מגדירים את מוצר ה-API. דף הגדרת המוצר כולל את החלקים הבאים:
    • פרטי המוצר: מידע בסיסי על מוצר ה-API, כמו השם, רמת הגישה (פרטית, ציבורית או פנימית) והיקפי הגישה של OAuth.
    • פעולות: קבוצות של proxy ל-API, נתיבי משאבים ו-HTTP methods שנתמכים על ידי מוצר ה-API הזה. אפשר גם להגדיר מכסות לכל פעולה.
    • פעולות LLM: קבוצות של פרוקסי API, מודלים, נתיבי משאבים ושיטות HTTP לפעולות LLM שנתמכות על ידי מוצר ה-API הזה. אפשר גם להגדיר מגבלות על מכסת האסימונים לכל פעולה.
    • פעולות GraphQL: קבוצות של פרוקסי API, נתיבי משאבים וסוגי פעולות GraphQL שנתמכים במוצר ה-API הזה. סוגי הפעולות הנתמכים ב-GraphQL כוללים שאילתות ושינויים. אפשר לציין סוג אחד או את שניהם. בדומה לפרוקסי של API מבוסס REST, אפשר להגדיר מכסות לכל פעולה.
    • gRPC Operations: מציינים שרתי proxy ל-gRPC API ושיטות gRPC שנתמכות על ידי מוצר ה-API הזה. בדיוק כמו בפרוקסי של API מבוסס-REST, אפשר להגדיר מכסות על פעולות.
    • מאפיינים מותאמים אישית: צמדי מפתח/ערך שעוזרים לכם לשלוט בהרצת ה-proxy ל-API.

    כל אחד מהחלקים האלה מתואר בקטעים הבאים.

  4. כשתסיים, לחץ על שמור. המערכת יוצרת את מוצר ה-API החדש ב-Apigee. עכשיו אפשר לצרף את המוצר לאפליקציה למפתחים. אפשר לעיין במאמר בנושא שליטה בגישה לממשקי API באמצעות רישום אפליקציות. דוגמאות נוספות זמינות במאמרים אבטחת API באמצעות דרישת מפתחות API ואבטחת API באמצעות OAuth.

פרטי המוצר

בקטע Product details (פרטי המוצר), מזינים מידע בסיסי על מוצר ה-API החדש. בטבלה הבאה מתוארים השדות בקטע הזה:

שדה חובה? תיאור
Name חובה

השם הפנימי של מוצר ה-API. משתמשים בערך הזה בקריאות ל-Apigee API שמפנות למוצר ה-API. הערך של השדה Name יכול לכלול תווים אלפאנומריים, רווחים ואת התווים הבאים: _ - . # $ %

לדוגמה, My API Product או my-product.
Display name חובה

הגדרת השם שיוצג בממשק המשתמש של Apigee למוצר ה-API. אפשר לערוך את השם המוצג של מוצר ה-API בכל שלב.

התווים המיוחדים יכולים להיכלל ב-Display name.

לדוגמה, <My> API Product!!!.
Description אופציונלי

מחרוזת שיכולה לעזור לכם לזכור את המטרה או הפונקציה של מוצר ה-API. התיאור יכול לכלול תווים מיוחדים.

לדוגמה, The one where I let dev apps read but not write to the "/accounts" endpoints.
Space אופציונלי

אם הפעלתם את Apigee Spaces בארגון, תוכלו לשייך את מוצר ה-API למרחב שתבחרו מתוך רשימת האפשרויות הזמינות. מידע נוסף זמין במאמר סקירה כללית של Apigee Spaces.
Environment אופציונלי

מזהה את הסביבות שהגישה אליהן מותרת למוצר ה-API. אם לא מציינים סביבות, מוצר ה-API מאפשר שימוש בכל הסביבות.

הסביבות שבוחרים בשדה הזה מגבילות את הגישה לשרתי proxy של API בהתאם למיקום הפריסה שלהם. לדוגמה, אם שרת proxy ל-API‏ A נפרס בסביבות test ו-prod, אבל במוצר ה-API נבחרה רק הסביבה test, קריאה ל-API של אפליקציית המפתחים המתאימה תאפשר גישה רק לשרת proxy ל-API‏ A שנפרס בסביבה test. מידע נוסף על סביבות זמין במאמר מידע על סביבות וקבוצות סביבות.
Access חובה רמת הגישה שניתנת למשתמשים במוצר ה-API הזה. מידע נוסף מופיע במאמר בנושא רמות גישה.
Automatically approve access requests אופציונלי (ברירת המחדל היא 'נבחר')

האפשרות הזו מאפשרת אישור אוטומטי של בקשות למפתחות שמתקבלות עבור מוצר ה-API הזה מכל אפליקציה. כדי לדרוש אישור ידני של מפתחות, צריך להשבית את האפשרות הזו.

ברירת המחדל נבחרת, כלומר מוצר ה-API הזה מאשר אוטומטית בקשות למפתחות.

אם בוחרים באישור ידני של מפתחות, צריך לאשר בקשות למפתחות שמגיעות מכל אפליקציה שמשתמשת במוצר ה-API הזה. כדי לאשר מפתחות באופן ידני:

  • ממשק משתמש: בוחרים באפשרות פרסום > אפליקציות, בוחרים את האפליקציה ועורכים אותה. ואז לוחצים על אישור.
  • ‫API: אפשר להשתמש ב-Developer app keys API.

מידע נוסף זמין במאמר בנושא רישום אפליקציות וניהול מפתחות API.
API quota limit אופציונלי

הגדרת מגבלות על מספר הבקשות שמותר לשלוח למוצר ה-API הזה. הערך הזה מתייחס לסכום של כל הבקשות של הפעולות במוצר ה-API הזה.

הערך הזה מוחלף על ידי הגבלות מכסה ספציפיות יותר שמוגדרות בפעולות שאתם מגדירים במוצר ה-API.

הזנת ערך מכסה לא מחילה באופן אוטומטי הגבלות על מספר הקריאות שאפשר לבצע דרך מוצר ה-API. צריך גם להוסיף את מדיניות המכסה לשרתי proxy ל-API שאליהם מתייחס מוצר ה-API.

מידע נוסף זמין במאמר בנושא מכסות.
LLM token quota limit אופציונלי

הגדרת מכסת טוקנים למוצר API. כך תוכלו לנהל ולהגביל את צריכת האסימונים בקריאות ל-API של מודלים גדולים של שפה (LLM) במהלך תקופה מוגדרת (לדוגמה, דקה, שעה, יום או חודש).

כשיוצרים מוצר API, מגדירים את LLM token quota limit לערך Enabled ואז מזינים ערך.

מידע נוסף מופיע במאמר בנושא מדיניות LLMTokenQuota.
Allowed OAuth scope אופציונלי אם אתם משתמשים ב-OAuth עם מוצר ה-API, צריך להזין רשימה מופרדת בפסיקים של היקפי OAuth שאתם רוצים שמוצר ה-API יאפשר (כמו Read או היקפים אחרים שאפליקציות שולחות עם הקריאות שלהן ל-API). מידע נוסף על היקפי הרשאות של OAuth

תפעול

מציינים פעולות שמותרות ב-proxy ל-API שמבוסס על HTTP, כולל נתיבי משאבים, methods של HTTP ומכסות. באמצעות פעולות אפשר לקבוע אילו שיטות REST יהיו זמינות במוצר API, לאילו נתיבי משאבים תהיה גישה, וכמה קריאות כאלה אפשר לבצע (עם מכסה).

כדי להגדיר את פרטי הפעולה, לוחצים על + הוספת פעולה בקטע פעולות. מוצג התצוגה Operation.

שדה חובה? תיאור
API proxy חובה

בוחרים את ה-proxy ל-API לשיוך לפעולה הזו.
Path חובה

מזינים את נתיב המשאב לפעולה.

אפשר להשתמש בנתיב הפעולה כדי לאשר או לדחות בקשות ל-URI ספציפיים. לדוגמה, אם מגדירים את המקור של הפעולה כ-music API proxy עם נתיב בסיס של /music, מוצר ה-API מאפשר קריאות לכל נתיבי המשנה שמתחת ל-/music. עם זאת, אם רוצים שמוצר ה-API יאפשר גישה רק לנתיב המשאב venues עם ה-URI‏ /music/venues, צריך להוסיף את /venues כנתיב של הפעולה. אפשר לעשות את זה לכל הפעולות או לפעולות ספציפיות.

במקרה הזה, שיחות אל /music/venues?name=paramount מותרות, אבל שיחות אל /music/artists?name=Jack%Johnson חסומות.

שימו לב שיש כללים מיוחדים לשימוש בתווים כלליים בנתיבי משאבים, כמו שמתואר במאמר בנושא הגדרת נתיבי משאבים.
Methods אופציונלי

בוחרים שיטה אחת או יותר של בקשות HTTP מהרשימה הנפתחת. (השיטות האלה נקראות לפעמים פעלים של HTTP). ‫Apigee מאפשר בקשות ל-proxy ל-API שתואמות רק לשיטות שאתם בוחרים.

ברירת המחדל היא ללא בחירה, מה שמאפשר בקשות עם כל שיטות ה-HTTP.

אם לא בוחרים לפחות שיטה אחת, המערכת של Apigee מוסיפה את הערך ALL לשדה הזה כששומרים את הפעולה.

מידע על הפונקציונליות של שיטות בקשות HTTP זמין במאמר שיטות בקשות HTTP.
Quota אופציונלי מציינים את הגבלות המכסה לפעולה הזו. פרטים על אופן הספירה של המכסות מופיעים במאמר הסבר על מוני המכסות.
Custom attributes אופציונלי מידע על מאפיינים מותאמים אישית

פעולות LLM

מציינים את הפעולות שמותרות ב-proxy ל-API שמבוסס על LLM, כולל נתיבי משאבים, מודלים, methods של HTTP ומכסות אסימונים. הפעולות של LLM מאפשרות לכם לקבוע לאילו מודלים תהיה גישה וכמה טוקנים אפשר להשתמש במוצר API.

כדי להגדיר פרטים של פעולות LLM, לוחצים על + הוספת פעולה בקטע פעולות LLM. מוצג התצוגה LLM Operation.

שדה חובה? תיאור
Proxy חובה

בוחרים את ה-proxy ל-API לשיוך לפעולת ה-LLM הזו.
Path חובה

מזינים את נתיב המשאב לפעולת ה-LLM. לרוב, זו הדרך למודל או לפונקציה ספציפיים של LLM.

לדוגמה, אם יש לכם proxy ל-API עם נתיב בסיס של /llm, ואתם רוצים לספק גישה למודל ספציפי בנתיב /llm/gemini-pro, תזינו /gemini-pro כנתיב הפעולה.

אפשר להשתמש בתווים כלליים לחיפוש בנתיב המשאב. לדוגמה, נתיב של /models/* יאפשר גישה לכל המודלים בנתיב /models/.
Models חובה

בוחרים את מודל ה-LLM לשיוך לפעולה הזו. המודלים הזמינים תלויים בהגדרות של proxy ל-API.
Method אופציונלי

בוחרים שיטה אחת או יותר של בקשות HTTP. בדרך כלל, הנתיב הזה הוא POST.

אם לא בוחרים שיטה, Apigee מאפשר בקשות עם כל שיטת HTTP. כששומרים את הפעולה, אם לא נבחרה שיטה, הערך ALL יוכנס.
LLM Token Quota אופציונלי מציינים מגבלות מכסה מבוססות-טוקן לפעולה הזו. זה יכול לכלול מגבלות על מספר האסימונים לדקה, ליום וכו'.
Custom attributes אופציונלי מידע על מאפיינים מותאמים אישית

פעולות GraphQL

כדי להגדיר פרטים של פעולת GraphQL, לוחצים על + הוספת פעולה בקטע פעולות GraphQL. מוצג התצוגה Operation. אפשר לעיין גם במאמר בנושא שימוש ב-GraphQL.

שדה חובה? תיאור
API proxy חובה

בוחרים את ה-proxy ל-API לשיוך לפעולה הזו.
Operation name חובה

מציינים שם לפעולה
Operation type אופציונלי

בוחרים סוג אחד או יותר של פעולת GraphQL מהרשימה הנפתחת. ‫Apigee מאפשר בקשות ל-proxy ל-API שתואמות רק לסוגי הפעולות שאתם בוחרים.

ברירת המחדל היא ללא בחירה, כך שאפשר לשלוח בקשות עם כל סוג פעולה.

אם לא בוחרים לפחות סוג אחד, המערכת של Apigee מוסיפה את הערך ALL לשדה הזה כששומרים את הפעולה.

מידע על הפונקציונליות של סוגי הפעולות ב-GraphQL זמין במאמר Queries and Mutations.
Quota אופציונלי מציינים את הגבלות המכסה לפעולה הזו. המכסה הזו מחליפה את המכסה שהוגדרה במוצר ה-API. Quota
Custom attributes אופציונלי מידע על מאפיינים מותאמים אישית

gRPC Operations

כדי להגדיר פרטים של פעולת gRPC, לוחצים על + הוספת פעולה בקטע פעולות gRPC. התצוגה Operation מופיעה. אפשר לקרוא גם על יצירת שרתי proxy ל-gRPC API.

שדה חובה? תיאור
API proxy חובה

בוחרים את ה-proxy ל-API לשיוך לפעולה הזו.
Service name חובה

מציינים שם לפעולה.

בגרסה הנוכחית, אין אפשרות לציין את שם שרת היעד. (שם השירות ושרת היעד זהים).

gRPC methods in service אופציונלי

מזינים את שיטות ה-gRPC הזמינות, ואם יש כמה שיטות, מפרידים ביניהן באמצעות פסיקים.

Quota אופציונלי מציינים את מגבלות המכסה לפעולות האלה. המכסה הזו מחליפה את המכסה שמוגדרת במוצר ה-API. Quota
Custom attributes אופציונלי מידע על מאפיינים מותאמים אישית

מאפיינים מותאמים אישית

מאפיינים מותאמים אישית הם צמדי מפתח/ערך שאפשר להשתמש בהם בדרכים רבות, כולל כדי לשלוט בהרצה של proxy ל-API.

בסך הכול, למוצר API יכולים להיות עד 18 מאפיינים מותאמים אישית, כולל אלה שמוגדרים בפעולות.

לדוגמה, אפשר ליצור מאפיין מותאם אישית בשם deprecated עם ערך של true או false. בתהליך של proxy ל-API, אפשר לבדוק את הערך של מאפיין deprecated של מוצר ה-API. אם הערך שלו הוא true, אפשר להקפיץ הודעת שגיאה (throw) באמצעות מדיניות RaiseFault כי רוצים שהפעולה הזו תתנהג כאילו היא יצאה משימוש ואין לה יותר תמיכה.

מכסה

אפשר להגדיר את מכסת השימוש למוצר ה-API או לכל היקף פעולה. יש שלושה שדות שחובה לציין כשמגדירים מכסה:

הוספת מכסת נפח לפעולה
  • המספר המקסימלי של בקשות שמותר לאפליקציה של מפתח לשלוח במהלך התקופה שצוינה. השדה הזה תואם לרכיב <Allow> במדיניות Quota.
  • מרווח הזמן לאיפוס המכסה. השדה הזה תואם לרכיב <Interval> במדיניות מכסות.
  • היחידה של תקופת האיפוס (או יחידת הזמן), כמו יום, שבוע או חודש. השדה הזה תואם לרכיב <TimeUnit> במדיניות מכסת השימוש.

בדוגמה הזו מוגדרת מגבלה של 1,000 בקשות למוצר ה-API ביום, על ידי הוספה של:

  • ‫1,000 כמספר המקסימלי של הבקשות.
  • ‫1 למרווח הזמן לאיפוס.
  • ‫day (יום) ליחידת תקופת האיפוס.
הוספת מכסת בקשות חדשה לפעולה עם 1,000 בקשות ביום

כשמגדירים מכסה לפעולה, צריך להזין ערכים בכל שלושת השדות בקטע Quota.

אפשר להגדיר מכסה נפרדת לכל פעולה. אם פעולה מציינת כמה שיטות HTTP, המכסה חלה על כל השיטות בפעולה הזו. כדי לאפשר מכסות נפרדות לכל שיטה, מגדירים כמה פעולות עם שיטה אחת בכל פעולה.

אם מגדירים את הערכים האלה גם במדיניות מכסה וגם במוצר ה-API (בממשק המשתמש, כמו שמתואר כאן, או באמצעות API של מוצרי API), ההגדרות של מוצר ה-API בממשק המשתמש או ב-API מקבלות עדיפות.

הגדרה של נתיבי משאבים

חשוב לשים לב לכללים הבאים לגבי נתיבי משאבים:

  • ‫/: מציין שנתיב הבסיס וכל נתיבי המשנה של נתיב הבסיס נתמכים.
  • ‫/**: מציין שיש תמיכה בכל נתיבי המשנה של נתיב הבסיס (אבל לא בנתיב הבסיס).
  • ‫/*: מציין שנתמכים רק מזהי URI ברמה אחת מתחת לנתיב הבסיס.
  • נתיבי משאבים שצוינו במוצר ה-API או בפעולות שלו חלים על כל שרתי ה-proxy ל-API שנוספו למוצר ה-API.
  • נתיבי משאבים כוללים יותר, פחות ספציפיים, מקבלים עדיפות על פני נתיבים ספציפיים יותר. לדוגמה, אם מוסיפים את / ואת /**, נתיב המשאב / מקבל עדיפות והמערכת מתעלמת מנתיב המשאב /**.

שימוש בתווים כלליים בנתיבי משאבים

חשוב לציין שבהגדרות של נתיבי משאבים ב-Apigee, אי אפשר להשתמש בכוכבית אחת (*) או בשתי כוכביות (**) כחלק משם של פלח נתיב (לדוגמה, /abc*/a), אבל אפשר להשתמש בהן כפלח נתיב מלא כדי לייצג תו כללי לחיפוש (לדוגמה, /*/a) או התאמה חמדנית של נתיב (לדוגמה, /abc/**).

לדוגמה:

  • הערכים האפשריים: /*/a או /abc/**. תו כללי הוא נתיב משנה בפני עצמו.
  • לא תקין: /abc/*a או /abc*/a. התו הכללי משולב עם תווים אחרים בנתיב המשנה.

הכלל הזה מבטיח שהתו הכללי יפורש כplaceholder ברור ומפורש עבור פלח שלם של נתיב, ולא כתבנית להתאמה בתוך שם של פלח נתיב יחיד.

התנהגות ברירת המחדל של נתיבי משאבים

בטבלה הבאה מוצגת התנהגות ברירת המחדל של מוצר API עבור נתיבי משאבים שונים. בדוגמה הזו, נתיב הבסיס של ה-proxy ל-API הוא /v1/weatherapikey. נתיב המשאב של מוצר ה-API חל על סיומת הנתיב אחרי נתיב הבסיס.

URI של בקשה ניתנה הרשאה ל-/ ניתנה הרשאה ל-/* ניתנה הרשאה ל-/** ניתנה הרשאה ל-/*/2/** ניתנה הרשאה ל-/*/2/*
/v1/weatherapikey
/v1/weatherapikey/
/v1/weatherapikey/1
/v1/weatherapikey/1/
/v1/weatherapikey/1/2
/v1/weatherapikey/1/2/
/v1/weatherapikey/1/2/3/
/v1/weatherapikey/1/a/2/3/

נתיב משאב של / במוצר API תומך בנתיב הבסיסי ובכל נתיבי המשנה. לדוגמה, אם נתיב הבסיס של ה-proxy ל-API הוא /v1/weatherapikey, מוצר ה-API תומך בבקשות אל /v1/weatherapikey ואל כל נתיבי המשנה, כמו /v1/weatherapikey/forecastrss,‏ /v1/weatherapikey/region/CA וכן הלאה.

מידע נוסף זמין במאמר הסבר על הגדרת מוצר API.

עריכת מוצר API

כדי לערוך מוצר API:

  1. עוברים לדף הסקירה הכללית מוצרים:

    לדף API products

  2. לוחצים על השורה של מוצר ה-API שרוצים לערוך. פרטי מוצר ה-API מוצגים ב-Apigee.
  3. לוחצים על עריכה.

  4. עורכים את ההגדרות של מוצר ה-API לפי הצורך.

    אי אפשר לערוך משאב API קיים. במקום זאת, אם רוצים לשנות את הערך, צריך למחוק את משאב ה-API ולהוסיף גרסה חדשה עם הערכים המתוקנים.

    יכול להיות שתצטרכו למחוק משאב אם הוא לא פועל כמו שצריך או אם הוא דורש פיתוח נוסף. אחרי המחיקה, המשאב הזה כבר לא חלק ממוצר ה-API הנוכחי. לא תהיה יותר גישה לאפליקציות שמשתמשות במוצר ה-API למשאב שנמחק. משאבים שנמחקו מוסרים ממוצר API, אבל לא נמחקים מהמערכת, כך שעדיין אפשר להשתמש בהם במוצרי API אחרים.

  5. (אופציונלי) אם הפעלתם את Apigee Monetization, לוחצים על Add rateplan כדי ליצור תוכנית תמחור למוצר ה-API.

  6. לוחצים על Save.

השינויים ייכנסו לתוקף תוך זמן קצר (כחמש דקות).

מחיקת מוצר API

כדי למחוק מוצר API, צריך לבטל את הרישום או את השיוך של כל אפליקציות המפתחים שמשויכות למוצר. אפשר לעשות זאת על ידי מחיקת האפליקציות או ביטול מפתחות ה-API של האפליקציות.

כדי למחוק מוצר API:

  1. עוברים לדף הסקירה הכללית מוצרים:

    לדף API products

  2. פותחים את התפריט Actions בשורה של מוצר ה-API שרוצים למחוק ובוחרים באפשרות Delete.
  3. אחרי שמאשרים את פעולת המחיקה, המחיקה מתבצעת תוך זמן קצר (כחמש דקות).