כרגע מוצג התיעוד של Apigee Edge.
כניסה למסמכי התיעוד של
Apigee X. מידע
מה
המדיניות של אימות מפתח API מאפשרת לאכוף אימות של מפתחות API בזמן ריצה, ומאפשרת רק לאפליקציות שיש להן מפתחות API מאושרים לגשת לממשקי ה-API. המדיניות הזו מבטיחה שמפתחות ה-API חוקיים, לא בוטלו ושאושרו לשימוש במשאבים הספציפיים שמשויכים למוצרי ה-API שלך.
טעימות
מפתח בפרמטר בשאילתה
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.queryparam.apikey" /> </VerifyAPIKey>
בדוגמה הזו, המדיניות מצפה למצוא את מפתח ה-API במשתנה זרימה שנקרא
request.queryparam.apikey
. המשתנה request.queryparam.{name}
הוא משתנה זרימה סטנדרטי של Edge שמאוכלס בערך של פרמטר שאילתה שהועבר
בבקשת הלקוח.
הפקודה 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 שמאוכלס בערך של כותרת שהועברה
בבקשת הלקוח.
ב-cURL הבא מוצג האופן שבו מעבירים את מפתח ה-API בכותרת:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
מפתח במשתנה
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="requestAPIKey.key"/> </VerifyAPIKey>
המדיניות יכולה להפנות לכל משתנה שמכיל את המפתח. המדיניות בדוגמה הזו מחלצת את מפתח ה-API ממשתנה שנקרא requestAPIKey.key.
אתם קובעים איך המשתנה הזה מאוכלס. לדוגמה, אפשר להשתמש במדיניות 'חילוץ משתני' כדי לאכלס את 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 מאכלס באופן אוטומטי קבוצה של משתני זרימה כשמפעילים את המדיניות 'אימות מפתח API' של מפתח API חוקי. אפשר להשתמש במשתנים האלה כדי לגשת למידע כמו שם האפליקציה, מזהה האפליקציה ומידע על המפתח או החברה שרשם את האפליקציה. בדוגמה שלמעלה, אפשר להשתמש במדיניות של הקצאת הודעה כדי לגשת לשם הפרטי, לשם המשפחה ולכתובת האימייל של המפתח לאחר ההפעלה של מפתח ה-API לאימות.
כל המשתנים האלה מופיעים לפני:
verifyapikey.{policy_name}
בדוגמה הזו, שם המדיניות של אימות מפתח ה-API הוא "verify-api-key". לכן, מתייחסים
לשם הפרטי של המפתח שהגיש את הבקשה באמצעות גישה
למשתנה verifyapikey.verify-api-key.developer.firstName.
למידת Edge
מידע על המדיניות בנושא אימות מפתח API
כשמפתח רושם אפליקציה ב-Edge, Edge יוצר באופן אוטומטי זוג של מפתח צרכן וסוד. אפשר לראות את זוג מפתח הצרכן והסוד של האפליקציה בממשק המשתמש של Edge, או לגשת אליהם מ-Edge API.
בזמן רישום האפליקציה, המפתח בוחר מוצר API אחד או יותר לשיוך לאפליקציה, כאשר מוצר API הוא אוסף של משאבים שניתן לגשת אליהם דרך שרתי proxy של API. לאחר מכן, המפתח מעביר את מפתח ה-API (מפתח צרכן) כחלק מכל בקשה ל-API במוצר API שמשויך לאפליקציה. מידע נוסף זמין בסקירת הפרסום.
אפשר להשתמש במפתחות API כאסימוני אימות או כדי לקבל אסימוני גישה של OAuth. ב-OAuth, מפתחות API נקראים 'מזהה לקוח'. השמות יכולים לשמש לסירוגין. מידע נוסף זמין בדף הבית של OAuth.
Edge מאכלס באופן אוטומטי קבוצה של משתני זרימה כשמריצים את המדיניות 'אימות מפתח 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>
מאפיין | התיאור | ברירת המחדל | נוכחות |
---|---|---|---|
ר' |
הפניה למשתנה שמכיל את מפתח ה-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.
המדיניות מאכלסת כמה סוגים שונים של משתני זרימה, כולל:
- כללי
- אפליקציה
- המפַתח
- חברה
- ניתוח נתונים
לכל סוג של משתנה זרימה יש קידומת שונה. כל המשתנים הם סקלרים, מלבד אלה שצוינו במפורש כמערכים.
משתני זרימה כלליים
בטבלה הבאה מפורטים משתני הזרימה הכלליים שאוכלסו במדיניות 'אימות מפתח 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 לקריאה חוזרת (callback) של האפליקציה. בדרך כלל משמשת רק ל-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 חוקי. המשתנים האלה מאוכלסים רק במדיניות OAuth 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. מנהלי חשבון ארגוני יכולים לשנות את הסטטוס של אפליקציה למפתחים באמצעות ה-Management API. למידע נוסף, ראו אישור או ביטול של אפליקציה למפתחים. |
oauth.v2.FailedToResolveAPIKey |
401 | המדיניות מצפה למצוא את מפתח ה-API במשתנה שצוין ברכיב <APIKey> של המדיניות. השגיאה הזו מתרחשת כשהמשתנה הצפוי לא קיים (לא ניתן לפתור אותו). |
oauth.v2.InvalidApiKey |
401 | מפתח API התקבל על ידי Edge אבל הוא לא תקין. כש-Edge מחפש את המפתח במסד הנתונים שלו, הוא חייב להיות זהה בדיוק לערך שנשלח בבקשה. אם ה-API פעל בעבר, עליך לוודא שהמפתח לא נוצר מחדש. אם המפתח נוצר מחדש, תופיע השגיאה הזו אם תנסו להשתמש במפתח הישן. מידע נוסף מופיע במאמר רישום אפליקציות וניהול של מפתחות API. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | מפתח API התקבל על ידי Edge והוא תקין. עם זאת, הוא לא תואם למפתח שאושר באפליקציה למפתחים, שמשויך לשרת ה-API של ה-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>