המדיניות של ValidAPIKey

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

מסמך עזר של רכיב

בהמשך מפורטים הרכיבים והמאפיינים שאפשר להגדיר במדיניות הזו:

<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>

&lt;VerifyAPIKey&gt; מאפיינים

בדוגמה הבאה מוצגים המאפיינים של התג <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 של המדיניות הוא בשימוש.
נוכחות אופציונלי
סוג מחרוזת

&lt;APIKey&gt; רכיב

הרכיב הזה מציין את משתנה הזרימה שמכיל את מפתח ה-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 זמינות בכתובת שימוש בקצה 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 סוג האפליקציה – 'חברה' או 'Developer'.
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 חוקי. המשתנים האלה מאוכלסים רק על ידי מפתח ה-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 במשתנה שמצוין במדיניות &lt;APIKey&gt; רכיב. השגיאה הזו מתרחשת כשהערך צפוי אינו קיים (לא ניתן לפענח אותו).
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>

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