המדיניות של ValidAPIKey

אתם קוראים את מאמרי העזרה של 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

השם הפנימי של המדיניות. הערך של המאפיין name יכול לכלול אותיות, מספרים, רווחים, מקפים, קווים תחתונים ונקודות. הערך הזה לא יכול ארוך מ-255 תווים.

אפשר להשתמש ברכיב <DisplayName> כדי להוסיף תווית למדיניות עורך ה-Proxy של ממשק המשתמש לניהול בעל שם אחר בשפה טבעית.

 לא רלוונטי חובה
continueOnError

צריך להגדיר את הערך false כדי להחזיר שגיאה כשמדיניות נכשלת. המצב הזה צפוי של רוב כללי המדיניות.

יש להגדיר ל-true כדי שביצוע התהליך יימשך גם לאחר המדיניות נכשל.

 false אופציונלי
enabled

צריך להגדיר את הערך true כדי לאכוף את המדיניות.

צריך להגדיר את הערך false כדי להשבית את המדיניות. המדיניות לא תהיה אכיפה גם אם היא ממשיכה להיות מחוברת לזרימה.

 true אופציונלי
async

המאפיין הזה הוצא משימוש.

 false הוצא משימוש

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>
ברירת מחדל

לא רלוונטי

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

אלמנט <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. אדמין בארגון יכול לשנות את הסטטוס של אפליקציית מפתחים באמצעות Management API. אישור או ביטול אישור של אפליקציה למפתחים
oauth.v2.FailedToResolveAPIKey 401 המדיניות מצפה למצוא את מפתח ה-API במשתנה שצוין ברכיב <APIKey> של המדיניות. השגיאה הזו מתרחשת כשהמשתנה הצפוי לא קיים (אי אפשר לפתור את הבעיה).
oauth.v2.InvalidApiKey 401 מפתח API התקבל על ידי Edge, אבל הוא לא תקין. כש-Edge מחפש את המפתח במסד הנתונים שלו, הוא צריך להיות זהה בדיוק למפתח שנשלח בבקשה. אם ה-API פעל בעבר, צריך לוודא שהמפתח לא נוצר מחדש. אם המפתח נוצר מחדש, השגיאה הזו תופיע אם תנסו להשתמש במפתח הישן. פרטים נוספים מופיעים במאמר בנושא רישום אפליקציות וניהול מפתחות API.
oauth.v2.InvalidApiKeyForGivenResource 401 מערכת Edge קיבלה מפתח API תקין, אבל הוא לא תואם למפתח מאושר באפליקציה למפתחים שמשויכת לשרת ה-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>

נושאים קשורים