אתם קוראים את מאמרי העזרה של Apigee Edge.
כדאי לעיין במסמכי העזרה בנושא Apigee X. מידע

מה
המדיניות Verify API Key (אימות מפתח API) מאפשרת לאכוף אימות של מפתחות API בזמן ריצה, כך שרק אפליקציות עם מפתחות API מאושרים יוכלו לגשת לממשקי ה-API שלכם. המדיניות הזו מבטיחה שמפתחות ה-API תקפים, שלא בוטלו ושקיבלתם אישור להשתמש במשאבים הספציפיים שמשויכים למוצרי ה-API שלכם.
דוגמאות
מפתח בפרמטר של שאילתה
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
בדוגמה הזו, המדיניות מצפה למצוא את מפתח ה-API במשתנה של זרימת נתונים שנקרא request.queryparam.apikey
. המשתנה request.queryparam.{name}
הוא משתנה רגיל של Edge Flow שאוכלס בערך של פרמטר שאילתה שהועבר
בבקשת הלקוח.
הפקודה הבאה של curl
מעבירה את מפתח ה-API כפרמטר של שאילתה:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
מפתח בכותרת
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey" /> </VerifyAPIKey>
בדוגמה הזו, המדיניות מצפה למצוא את מפתח ה-API במשתנה של זרימת נתונים שנקרא request.header.x-apikey
. המשתנה request.header.{name}
הוא משתנה רגיל של Edge Flow שאוכלס בערך של כותרת שהועברה
בבקשת הלקוח.
בדוגמת ה-cURL הבאה אפשר לראות איך מעבירים את מפתח ה-API בכותרת:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
מפתח במשתנה
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
המדיניות יכולה להתייחס לכל משתנה שמכיל את המפתח. המדיניות בדוגמה הזו מחלצת את מפתח ה-API ממשתנה בשם requestAPIKey.key.
אתם קובעים איך המשתנה הזה יאוכלס. לדוגמה, אפשר להשתמש במדיניות Extract Variables כדי לאכלס את requestAPIKey.key מפרמטר שאילתה בשם myKey, כמו שמוצג בהמשך:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar"> <Source>request</Source> <QueryParam name="myKey"> <Pattern ignoreCase="true">{key}</Pattern> </QueryParam> <VariablePrefix>requestAPIKey</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
משתני זרימה של מדיניות הגישה
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars"> <AssignVariable> <Name>devFirstName</Name> <Ref>verifyapikey.verify-api-key.developer.firstName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devLastName</Name> <Ref>verifyapikey.verify-api-key.developer.lastName</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <AssignVariable> <Name>devEmail</Name> <Ref>verifyapikey.verify-api-key.developer.email</Ref> <Value>ErrorOnCopy</Value> </AssignVariable> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="request"/> </AssignMessage>
Edge מאכלס באופן אוטומטי קבוצה של משתני זרימה כשמבצעים את מדיניות Verify API Key (אימות מפתח API) עבור מפתח API תקין. אפשר להשתמש במשתנים האלה כדי לגשת למידע כמו שם האפליקציה, מזהה האפליקציה ופרטים על המפתח או החברה שרשמו את האפליקציה. בדוגמה שלמעלה, אתם משתמשים במדיניות Assign Message כדי לגשת לשם הפרטי, לשם המשפחה ולכתובת האימייל של המפתח אחרי שמבצעים את Verify API Key.
לכל המשתנים האלה יש קידומת:
verifyapikey.{policy_name}
בדוגמה הזו, שם המדיניות של Verify API key הוא verify-api-key. לכן, אתם צריכים להפנות לשם הפרטי של המפתח ששולח את הבקשה על ידי גישה למשתנה verifyapikey.verify-api-key.developer.firstName.
מידע על Edge
מידע על המדיניות בנושא אימות מפתח API
כשמפתח רושם אפליקציה ב-Edge, המערכת יוצרת באופן אוטומטי זוג של מפתח וסוד צרכן. אפשר לראות את מפתח הצרכן ואת הזוג הסודי של האפליקציה בממשק המשתמש של Edge או לגשת אליהם דרך Edge API.
בזמן רישום האפליקציה, המפתח בוחר מוצרי API אחד או יותר לשיוך לאפליקציה. מוצר API הוא אוסף של משאבים שאפשר לגשת אליהם באמצעות שרתי proxy ל-API. לאחר מכן המפתח מעביר את מפתח ה-API (מפתח הצרכן) כחלק מכל בקשה ל-API במוצר API שמשויך לאפליקציה. מידע נוסף זמין במאמר סקירה כללית על פרסום.
אפשר להשתמש במפתחות API כאסימוני אימות, או כדי לקבל אסימוני גישה מסוג OAuth. ב-OAuth, מפתחות API נקראים 'מזהה לקוח'. אפשר להשתמש בשמות לסירוגין. מידע נוסף זמין במאמר דף הבית של OAuth.
Edge מאכלס באופן אוטומטי קבוצה של משתני זרימה כשמבצעים את מדיניות Verify API Key (אימות מפתח API). מידע נוסף מופיע בקטע משתני זרימה שבהמשך.
הפניה לרכיב
אלה הרכיבים והמאפיינים שאפשר להגדיר במדיניות הזו:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1"> <DisplayName>Custom label used in UI</DisplayName> <APIKey ref="variable_containing_api_key"/> </VerifyAPIKey>
מאפיינים של <VerifyAPIKey>
בדוגמה הבאה מוצגים המאפיינים בתג <VerifyAPIKey>
:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
בטבלה הבאה מתוארים מאפיינים שמשותפים לכל רכיבי ההורה של המדיניות:
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
name |
השם הפנימי של המדיניות. הערך של המאפיין אפשר להשתמש ברכיב |
לא רלוונטי | חובה |
continueOnError |
צריך להגדיר את הערך יש להגדיר ל- |
false | אופציונלי |
enabled |
צריך להגדיר את הערך צריך להגדיר את הערך |
true | אופציונלי |
async |
המאפיין הזה הוצא משימוש. |
false | הוצא משימוש |
<DisplayName> רכיב
צריך להשתמש בנוסף למאפיין name
כדי להוסיף תווית למדיניות
עורך proxy של ממשק משתמש לניהול עם שם אחר בשפה טבעית.
<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל |
לא רלוונטי אם משמיטים את הרכיב הזה, הערך של המאפיין |
---|---|
נוכחות | אופציונלי |
סוג | מחרוזת |
אלמנט <APIKey>
האלמנט הזה מציין את משתנה הזרימה שמכיל את מפתח ה-API. בדרך כלל, הלקוח שולח את מפתח ה-API כפרמטר של שאילתה, ככותרת HTTP או כפרמטר של טופס. לדוגמה, אם המפתח נשלח בכותרת שנקראת x-apikey
, המפתח יימצא במשתנה: request.header.x-apikey
ברירת מחדל | לא רלוונטי |
---|---|
נוכחות | חובה |
סוג | מחרוזת |
מאפיינים
בטבלה הבאה מתוארים המאפיינים של רכיב <APIKey>
מאפיין | תיאור | ברירת מחדל | נוכחות |
---|---|---|---|
ref |
הפניה למשתנה שמכיל את מפתח ה-API. מותר להשתמש רק במיקום אחד לכל מדיניות. |
לא רלוונטי | חובה |
דוגמאות
בדוגמאות האלה, המפתח מועבר בפרמטרים ובכותרת שנקראת x-apikey
.
כפרמטר של שאילתה:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.x-apikey"/> </VerifyAPIKey>
ככותרת HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.header.x-apikey"/> </VerifyAPIKey>
כפרמטר של טופס HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
סכימות
משתני תהליך
כשמחילים מדיניות של אימות מפתח API על מפתח API תקין, Edge מאכלס קבוצה של משתני זרימה. המשתנים האלה זמינים למדיניות או לקוד שמופעלים בהמשך התהליך, ולרוב משתמשים בהם כדי לבצע עיבוד בהתאמה אישית על סמך מאפיינים של מפתח ה-API, כמו שם האפליקציה, מוצר ה-API שמשמש לאישור המפתח או מאפיינים מותאמים אישית של מפתח ה-API.
המדיניות מאכלסת כמה סוגים שונים של משתני זרימה, כולל:
- כללי
- אפליקציה
- מפתח
- חברה
- Analytics
לכל סוג של משתנה של זרימת נתונים יש קידומת שונה. כל המשתנים הם סקלריים, אלא אם צוין במפורש שהם מערכים.
משתני זרימה כלליים
בטבלה הבאה מפורטים משתני הזרימה הכלליים שאוכלסו על ידי המדיניות Verify API Key (אימות מפתח API). לכל המשתנים האלה יש קידומת:
verifyapikey.{policy_name}
לדוגמה: verifyapikey.{policy_name}.client_id
המשתנים הזמינים כוללים:
משתנה | תיאור |
---|---|
client_id |
מפתח הצרכן (נקרא גם מפתח API או מפתח אפליקציה) שסופק על ידי האפליקציה ששולחת את הבקשה. |
client_secret |
הסוד של הצרכן שמשויך לטוקן הצרכן. |
redirection_uris |
כל מזהי ה-URI של ההפניות בבקשה. |
developer.app.id |
המזהה של אפליקציית הפיתוח ששולחת את הבקשה. |
developer.app.name |
שם האפליקציה של המפתח ששולחת את הבקשה. |
developer.id |
המזהה של המפתח שרשום כבעלים של האפליקציה ששולחת את הבקשה. |
developer.{custom_attrib_name} |
מאפיינים מותאמים אישית שנגזרים מפרופיל מפתח האפליקציה |
DisplayName |
הערך של מאפיין ה-<DisplayName> של המדיניות. |
failed |
הערך מוגדר כ-true אם האימות של מפתח ה-API נכשל. |
{custom_app_attrib} |
כל מאפיין בהתאמה אישית שנגזר מפרופיל האפליקציה. מציינים את השם של המאפיין המותאם אישית. |
apiproduct.name* |
שם מוצר ה-API שמשמש לאימות הבקשה. |
apiproduct.{custom_attrib_name}* |
כל מאפיין מותאם אישית שנגזר מפרופיל מוצר ה-API. |
apiproduct.developer.quota.limit* |
מגבלת המכסה שהוגדרה במוצר ה-API, אם יש כזו. |
apiproduct.developer.quota.interval* |
מרווח המכסה שמוגדר במוצר ה-API, אם יש כזה. |
apiproduct.developer.quota.timeunit* |
יחידת הזמן של המכסה שהוגדרה במוצר ה-API, אם יש כזו. |
* משתני מוצר ה-API מאוכלסים באופן אוטומטי אם מוצרי ה-API מוגדרים עם סביבה, שרתי proxy ומשאבים תקינים (שנגזרים מ-proxy.pathsuffix ). הוראות להגדרת מוצרי API מפורטות במאמר שימוש ב-Edge Management API לפרסום ממשקי API. |
משתנים של תהליך באפליקציה
המשתנים הבאים של זרימת העבודה, שמכילים מידע על האפליקציה, מאוכלסים על ידי המדיניות. לכל המשתנים האלה יש קידומת:
verifyapikey.{policy_name}.app
.
לדוגמה:
verifyapikey.{policy_name}.app.name
המשתנים הזמינים כוללים:
משתנה | תיאור |
---|---|
name |
שם היישום. |
id |
מזהה האפליקציה. |
accessType |
לא בשימוש ב-Apigee. |
callbackUrl |
כתובת ה-URL של הקריאה החוזרת של האפליקציה. בדרך כלל משתמשים בה רק ב-OAuth. |
DisplayName |
השם המוצג של האפליקציה. |
status |
סטטוס האפליקציה, למשל 'אושרה' או 'בוטלה'. |
apiproducts |
מערך שמכיל את רשימת מוצרי ה-API שמשויכים לאפליקציה. |
appFamily |
כל משפחת אפליקציות שמכילה את האפליקציה, או 'ברירת מחדל'. |
appParentStatus |
הסטטוס של האפליקציה הראשית, למשל 'פעילה' או 'לא פעילה' |
appType |
סוג האפליקציה, 'חברה' או 'מפתח'. |
appParentId |
המזהה של אפליקציית ההורה. |
created_at |
חותמת התאריך והשעה שבהן נוצרה האפליקציה. |
created_by |
כתובת האימייל של המפתח שיצר את האפליקציה. |
last_modified_at |
חותמת התאריך והשעה שבה האפליקציה עודכנה לאחרונה. |
last_modified_by |
כתובת האימייל של המפתח שעדכן את האפליקציה לאחרונה. |
{app_custom_attributes} |
כל מאפיין מותאם אישית של אפליקציה. מציינים את השם של המאפיין המותאם אישית. |
משתני זרימה למפתחים
המשתנים הבאים של זרימת העבודה, שמכילים מידע על המפתח, מאוכלסים על ידי המדיניות. לכל המשתנים האלה יש קידומת:
verifyapikey.{policy_name}.developer
לדוגמה:
verifyapikey.{policy_name}.developer.id
המשתנים הזמינים כוללים:
משתנה | תיאור |
---|---|
id |
הפונקציה מחזירה {org_name}@@@{developer_id} |
userName |
שם המשתמש של המפתח. |
firstName |
השם הפרטי של המפתח. |
lastName |
שם המשפחה של המפתח. |
email |
כתובת האימייל של המפתח. |
status |
הסטטוס של המפתח: פעיל, לא פעיל או login_lock. |
apps |
מערך של אפליקציות שמשויכות למפתח. |
created_at |
חותמת התאריך והשעה שבהם נוצר חשבון המפתח. |
created_by |
כתובת האימייל של המשתמש שיצר את המפתח. |
last_modified_at |
חותמת התאריך והשעה שבה בוצע השינוי האחרון במפתח. |
last_modified_by |
כתובת האימייל של המשתמש ששינה את פרטי המפתח. |
{developer_custom_attributes} |
כל מאפיין מותאם אישית למפתחים. מציינים את השם של המאפיין המותאם אישית. |
Company |
שם החברה, אם יש כזו, שמשויכת למפתח. |
משתני תהליך עבודה של חברה
משתני הזרימה הבאים מכילים מידע על החברה ומאוכלסים על ידי המדיניות. לכל המשתנים האלה יש קידומת:
verifyapikey.{policy_name}.company
לדוגמה:
verifyapikey.{policy_name}.company.name
המשתנים הזמינים כוללים:
משתנה | תיאור |
---|---|
name |
שם החברה. |
displayName |
השם המוצג של החברה. |
id |
מזהה החברה. |
apps |
מערך שמכיל את רשימת האפליקציות של החברה. |
appOwnerStatus |
הסטטוס של בעל האפליקציה: פעיל, לא פעיל או login_lock.
|
created_at |
חותמת התאריך והשעה שבהם החברה נוצרה. |
created_by |
כתובת האימייל של המשתמש שיצר את החברה. |
last_modified_at |
חותמת הזמן של התאריך והשעה שבהם בוצע השינוי האחרון בחברה. |
last_modified_by |
כתובת האימייל של המשתמש שערך את השינוי האחרון בחברה. |
{company_custom_attributes} |
כל מאפיין מותאם אישית של החברה. מציינים את השם של המאפיין המותאם אישית. |
משתנים ב-Analytics
המשתנים הבאים מאוכלסים אוטומטית ב-Analytics כשמחילים מדיניות של אימות מפתח API על מפתח API תקין. המשתנים האלה מאוכלסים רק על ידי המדיניות Verify API Key (אימות מפתח API) ומדיניות OAuth.
אפשר להשתמש במשתנים ובערכים כמאפיינים כדי ליצור דוחות ב-Analytics ולקבל תובנות לגבי דפוסי הצריכה של מפתחים ואפליקציות.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
הפניה לשגיאה
בקטע הזה מתוארים קודי השגיאה והודעות השגיאה שהוחזרו, ומשתני התקלה שמוגדרים על ידי Edge כשהמדיניות הזו גורמת לשגיאה. חשוב לדעת את המידע הזה אם אתם מפתחים כללי כשל כדי לטפל בתקלות. מידע נוסף זמין במאמר מה צריך לדעת? מידע על שגיאות שקשורות למדיניות וטיפול פגמים.
שגיאות זמן ריצה
השגיאות האלה עשויות להתרחש כשהמדיניות מופעלת.
קוד תקלה | סטטוס HTTP | סיבה |
---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | לחברה המשויכת לאפליקציית המפתח, שיש לה את מפתח ה-API שבו השתמשת, יש סטטוס לא פעיל. כשסטטוס של חברה מוגדר כלא פעיל, לא ניתן לגשת מפתחים או אפליקציות שמשויכים לאותה חברה. מנהל חשבון ארגוני יכול לשנות את הסטטוס של חברה באמצעות ממשק ה-API לניהול. למידע נוסף, ראו הגדרת הסטטוס של חברה מסוימת. |
keymanagement.service.DeveloperStatusNotActive |
401 |
המפתח שיצר את האפליקציה למפתחים שיש לו את מפתח ה-API שבו השתמשת סטטוס לא פעיל. כשהסטטוס של מפתח אפליקציות מוגדר כלא פעיל, כל האפליקציות למפתחים שנוצרו על ידי אותו מפתח יושבתו. משתמש עם הרשאת אדמין עם ההרשאות המתאימות (למשל, אדמין ארגוני) יכול לשנות את הסטטוס של מפתח בדרכים הבאות דרכים:
|
keymanagement.service.invalid_client-app_not_approved |
401 | האפליקציה למפתחים שמשויכת למפתח ה-API מבוטלת. אפליקציה שבוטלה לא יכולה לגשת למוצרי API ולא להפעיל אף ממשק API שמנוהל על ידי Apigee Edge. מנהל חשבון ארגוני יכול לשנות את הסטטוס של אפליקציה למפתחים באמצעות ממשק ה-API לניהול. ראו אישור או ביטול של אפליקציית המפתחים. |
oauth.v2.FailedToResolveAPIKey |
401 | המדיניות מצפה למצוא את מפתח ה-API במשתנה שמצוין במדיניות <APIKey> רכיב. השגיאה הזו מתרחשת כשהערך צפוי אינו קיים (לא ניתן לפענח אותו). |
oauth.v2.InvalidApiKey |
401 | Edge התקבל מפתח API, אבל הוא לא תקין. כש-Edge מחפש את המפתח הוא חייב להתאים בדיוק לנתונים שנשלחו בבקשה. אם ה-API פעל קודם צריך לוודא שהמפתח לא נוצר מחדש. אם המפתח נוצר מחדש, יוצגו לך השגיאה הזו מופיעה אם מנסים להשתמש במפתח הישן. מידע נוסף זמין במאמר רישום אפליקציות וניהול API . |
oauth.v2.InvalidApiKeyForGivenResource |
401 | התקבל מפתח API על ידי Edge, והוא תקין. עם זאת, הוא לא תואם מפתח שאושר באפליקציה למפתחים המשויך לשרת ה-proxy ל-API דרך מוצר. |
שגיאות פריסה
השגיאות האלו עשויות להתרחש כאשר פורסים שרת proxy שמכיל את המדיניות הזו.
שם השגיאה | סיבה |
---|---|
SpecifyValueOrRefApiKey |
לא צוינו ערך או מפתח ברכיב <APIKey> . |
משתני כשל
המשתנים האלה מוגדרים כשמתרחשת שגיאה בסביבת זמן הריצה. מידע נוסף זמין במאמר מה צריך לדעת? על שגיאות שקשורות למדיניות.
משתנים | איפה | דוגמה |
---|---|---|
fault.name="fault_name" |
fault_name הוא שם השגיאה, כפי שמצוין בטבלה שגיאות זמן ריצה שלמעלה. שם השגיאה הוא החלק האחרון בקוד השגיאה. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name הוא השם שצוין על ידי המשתמש של המדיניות שגרמה לבעיה. | oauthV2.VK-VerifyAPIKey.failed = true |
דוגמאות לתשובות שגיאה
{ "fault":{ "faultstring":"Invalid ApiKey", "detail":{ "errorcode":"oauth.v2.InvalidApiKey" } } }
{ "fault":{ "detail":{ "errorcode":"keymanagement.service.DeveloperStatusNotActive" }, "faultstring":"Developer Status is not Active" } }
דוגמה לכלל שגוי
<FaultRule name="FailedToResolveAPIKey"> <Step> <Name>AM-FailedToResolveAPIKey</Name> </Step> <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition> </FaultRule>