המדיניות של ValidAPIKey

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

מה

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

דוגמאות

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

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

verifyapikey.{policy_name}

מידע על המדיניות בנושא אימות מפתח 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">

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

&lt;DisplayName&gt; רכיב

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

<DisplayName>Policy Display Name</DisplayName>

אלמנט <APIKey>

האלמנט הזה מציין את משתנה הזרימה שמכיל את מפתח ה-API. בדרך כלל, הלקוח שולח את מפתח ה-API כפרמטר של שאילתה, ככותרת HTTP או כפרמטר של טופס. לדוגמה, אם המפתח נשלח בכותרת שנקראת x-apikey, המפתח יימצא במשתנה: request.header.x-apikey

מאפיינים

בטבלה הבאה מתוארים המאפיינים של רכיב <APIKey>

דוגמאות

בדוגמאות האלה, המפתח מועבר בפרמטרים ובכותרת שנקראת 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

המשתנים הזמינים כוללים:

משתנים של תהליך באפליקציה

המשתנים הבאים של זרימת העבודה, שמכילים מידע על האפליקציה, מאוכלסים על ידי המדיניות. לכל המשתנים האלה יש קידומת:

‫verifyapikey.{policy_name}.app.

לדוגמה:

verifyapikey.{policy_name}.app.name

המשתנים הזמינים כוללים:

משתני זרימה למפתחים

המשתנים הבאים של זרימת העבודה, שמכילים מידע על המפתח, מאוכלסים על ידי המדיניות. לכל המשתנים האלה יש קידומת:

verifyapikey.{policy_name}.developer

לדוגמה:

verifyapikey.{policy_name}.developer.id

המשתנים הזמינים כוללים:

משתני תהליך עבודה של חברה

משתני הזרימה הבאים מכילים מידע על החברה ומאוכלסים על ידי המדיניות. לכל המשתנים האלה יש קידומת:

verifyapikey.{policy_name}.company

לדוגמה:

verifyapikey.{policy_name}.company.name

המשתנים הזמינים כוללים:

משתנים ב-Analytics

המשתנים הבאים מאוכלסים אוטומטית ב-Analytics כשמחילים מדיניות של אימות מפתח API על מפתח API תקין. המשתנים האלה מאוכלסים רק על ידי המדיניות Verify API Key (אימות מפתח API) ומדיניות OAuth.

אפשר להשתמש במשתנים ובערכים כמאפיינים כדי ליצור דוחות ב-Analytics ולקבל תובנות לגבי דפוסי הצריכה של מפתחים ואפליקציות.

• apiproduct.name
• developer.app.name
• client_id
• developer.id

הפניה לשגיאה

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error responses

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>

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