ניהול מוצרי API

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

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

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

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

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

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

מעבר אל מוצרי API

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

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

יצירת מוצר API

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

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

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

    מעבר אל מוצרי API

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

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

  4. כשתסיים, לחץ על שמור. המערכת יוצרת את מוצר ה-API החדש. עכשיו אפשר לצרף את המוצר לאפליקציה למפתחים. אפשר לעיין במאמר שליטה בגישה לממשקי 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 לערך מופעל ואז מזינים ערך.

מידע נוסף מופיע במאמר בנושא מדיניות 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 ספציפיים. לדוגמה, אם מגדירים את המקור של הפעולה כ-API proxy‏ music עם נתיב בסיס של /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, כולל נתיבי משאבים, מודלים, שיטות 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. בפעולות של מודלים גדולים של שפה (LLM), בדרך כלל זה הנתיב 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

  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

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