מדיניות AccessEntity

מדיניות ניתנת להרחבה

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

המדיניות AccessEntity מאחזרת פרופילים של ישויות שאתם מציינים ממאגר הנתונים של Apigee. ‫The policy places the profile in a variable whose name follows the format AccessEntity.{policy_name}. אפשר להשתמש ב-AccessEntity כדי לגשת לפרופילים של הישויות הבאות:

  • אפליקציה
  • מוצר API
  • טוקן צרכן
  • מפתח

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

משתמשים במדיניות AccessEntity כדי לקבל נתוני פרופיל של ישות בפורמט XML (או JSON ב-Apigee hybrid) ומציבים אותם במשתנה. מזהים את הישות שרוצים לקבל על ידי ציון סוג הישות ומזהה אחד או יותר שמציינים איזו ישות מהסוג הזה רוצים לקבל. בהמשך, במדיניות אחרת, אפשר לאחזר את נתוני פרופיל הישות באמצעות מדיניות אחרת, כמו מדיניות ExtractVariables או מדיניות AssignMessage.

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

גישה לישויות AppGroups מ-AccessEntity

אפשר גם להשתמש ב-AccessEntity כדי לאחזר ישויות AppGroup. במאמר סוגי ישויות ומזהים נתמכים מפורטות ישויות קשורות.

מידע על קבוצות אפליקציות ועל הפונקציות הנתמכות מופיע במאמר שימוש בקבוצות אפליקציות לארגון הבעלות על אפליקציות.

דוגמאות

בדוגמאות הבאות מוצג שימוש ב-AccessEntity בשילוב עם מדיניות ExtractVariables ו-AssignMessage כדי לחלץ את כתובת האימייל של מפתח ולהוסיף אותה לכותרת ה-HTTP.

קבלת כתובת אימייל של מפתח לשימוש במדיניות אחרת

מגדירים את המדיניות של AccessEntity כדי לציין מאיזה פרופיל של ישות לקבל נתונים מ-Apigee, וגם איפה למקם את נתוני הפרופיל.

בדוגמה הבאה, המדיניות מקבלת פרופיל של ישות developer באמצעות מפתח API שמועבר כפרמטר של שאילתה כדי לזהות את המפתח. הפרופיל מוצב במשתנה שהשם שלו הוא AccessEntity.{policy_name}. לכן המשתנה שמוגדר על ידי המדיניות הזו יהיה AccessEntity.GetDeveloperProfile.

<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Apigee datastore. -->
  <EntityType  value="developer"/>
  <!-- We tell the policy to use the API key (presented as query parameter) to identify the developer. -->
  <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/>
</AccessEntity>

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

בדוגמה הבאה, מדיניות ExtractVariables מאחזרת ערך מהמשתנה AccessEntity.GetDeveloperProfile שהוגדר קודם על ידי AccessEntity.

שימו לב שהערך שאוחזר מצוין כביטוי XPath ברכיב XMLPayload. הערך שחולץ מוצב במשתנה developer.email.

<ExtractVariables name="SetDeveloperProfile">
  <!-- The source element points to the variable populated by AccessEntity policy.
  The format is <policy-type>.<policy-name>.
  In this case, the variable contains the whole developer profile. -->
  <Source>AccessEntity.GetDeveloperProfile</Source>
  <VariablePrefix>developer</VariablePrefix>
  <XMLPayload>
    <Variable name="email" type="string">
        <!-- You parse elements from the developer profile using XPath. -->
      <XPath>/Developer/Email</XPath>
    </Variable>
  </XMLPayload>
</ExtractVariables>

מדיניות AssignMessage הבאה מאחזרת את כתובת האימייל של המפתח שהוגדרה על ידי מדיניות ExtractVariables.

<!-- We'll use this policy to return the variables set in the developer profile,
just so that we can easily see them in the response. -->
<AssignMessage name="EchoVariables">
  <AssignTo createNew="false" type="response"></AssignTo>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="X-Developer-email">{developer.email}</Header>
    </Headers>
  </Set>
</AssignMessage>

הפניה לרכיב

המבנה הבסיסי של מדיניות AccessEntity הוא:

<AccessEntity name="policy_name">
  <EntityType  value="entity_type"/>
  <EntityIdentifier ref="entity_identifier" type="identifier_type"/>
  <SecondaryIdentifier ref="secondary_identifier" type="identifier_type"/>
</AccessEntity>

אפשר לגשת לכמה ישויות מאותו סוג על ידי קיבוץ שלהן ברכיב Identifiers:

<AccessEntity name="name_of_the_policy">
  <EntityType  value="type_of_entity"/>
  <Identifiers>
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*="identifier_type"/>
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifier_type"/><!-- optional -->
    </Identifier >
    <Identifier>
      <EntityIdentifier ref="reference_to_entity_identifier" type*="identifier_type"/>
      <SecondaryIdentifier ref="reference_to_secondary_entity_identifier" type="identifier_type"/><!-- optional -->
    </Identifier >
  </Identifiers>
</AccessEntity>

מאפיינים של <AccessEntity>

<AccessEntity async="false" continueOnError="false" enabled="true" name="policy_name">

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

מאפיין תיאור ברירת מחדל נוכחות
name

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

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

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

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

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

 FALSE אופציונלי
enabled

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

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

 TRUE אופציונלי
async

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

 FALSE הוצא משימוש

אלמנט <DisplayName>

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

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

לא רלוונטי

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

אלמנט <EntityIdentifier>

מציין את הישות הספציפית – מהסוג שצוין ב-EntityType – שרוצים לקבל.

<EntityIdentifier ref="value_variable" type="identifier_type"/>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג String

מאפיינים

מאפיין תיאור ברירת מחדל נוכחות סוג
ref

המשתנה שמספק את המקור של המזהה, כמו request.queryparam.apikey.

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

דוגמה

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetAPIProduct">
    <DisplayName>GetAPIProduct</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/>
    <SecondaryIdentifier ref="developer.id" type="developerid"/>
</AccessEntity>

אלמנט <EntityType>

מציין את סוג הישות שיש לאחזר ממאגר הנתונים.

<EntityType  value="entity_type"/>
ברירת מחדל לא רלוונטי
נוכחות חובה
סוג String

משתמשים ברכיב EntityIdentifier כדי לציין איזו ישות מהסוג הנתון רוצים. במאמר סוגים ומזהים נתמכים של ישויות מפורטים סוגי הישויות.

מאפיינים

מאפיין תיאור ברירת מחדל נוכחות סוג
value אחד מסוגי הישויות הנתמכים. רשימה של סוגי ישויות ומזהים נתמכים מופיעה במאמר סוגי ישויות ומזהים נתמכים. ללא חובה String

אלמנט <OutputFormat>

מציינת באיזה פורמט מדיניות AccessEntity מוחזרת: XML או JSON.

<OutputFormat>XML</OutputFormat>
ברירת מחדל

XML

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

רכיב <SecondaryIdentifier>

בצירוף EntityIdentifier, מציין ערך לזיהוי המופע הרצוי של EntityType.

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>
ברירת מחדל לא רלוונטי
נוכחות אופציונלי
סוג String

שימוש ב-SecondaryIdentifier כשמציינים רק EntityIdentifier לא מבטיח שתקבלו ישות אחת. מידע נוסף זמין במאמר צמצום התוצאות באמצעות מזהים משניים.

אין תמיכה בשימוש בכמה רכיבי SecondaryIdentifier.

מאפיינים

מאפיין תיאור ברירת מחדל נוכחות סוג
ref

המשתנה שמספק את המקור של המזהה, כמו request.queryparam.apikey.

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

דוגמה

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetAPIProduct">
    <DisplayName>GetAPIProduct</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/>
    <SecondaryIdentifier ref="developer.id" type="developerid"/>
</AccessEntity>

הערות שימוש

צמצום התוצאות באמצעות מזהים משניים

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

הגדרת המדיניות הראשונה, שאולי תהיה רחבה, יכולה להיראות כך:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="request.queryparam.apikey" type="consumerkey"/>
</AccessEntity>

אפליקציה יכולה להיות משויכת לכמה מוצרי API, ולכן שימוש רק במזהה האפליקציה לא תמיד יחזיר את מוצר ה-API הרצוי (יכול להיות שתקבלו רק את הראשון מבין כמה מוצרים תואמים).

במקום זאת, כדי לקבל תוצאה מדויקת יותר, אפשר להשתמש בSecondaryIdentifier. לדוגמה, יכול להיות שיש לכם משתני appname ו-developerid בתהליך, כי הם מאוכלסים כברירת מחדל במהלך חילופי נתונים ב-OAuth 2.0. אתם יכולים להשתמש בערכים של המשתנים האלה במדיניות AccessEntity כדי לקבל פרטי פרופיל באפליקציה ששולחת את הבקשה.

הגדרת מדיניות ספציפית יותר יכולה להיראות כך:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessEntity async="false" continueOnError="false" enabled="true" name="GetApp">
    <DisplayName>GetAppProfile</DisplayName>
    <EntityType value="apiproduct"></EntityType>
    <EntityIdentifier ref="developer.app.name" type="appname"/>
    <SecondaryIdentifier ref="developer.id" type="developerid"/>
</AccessEntity>

סוגי ישויות ומזהים נתמכים

הפונקציה AccessEntity תומכת בסוגי הישויות ובמזהים הבאים.

הערך של EntityType סוגי מזהי ישויות סוגי מזהים משניים
apiproduct appid apiresource
apiproductname
appname apiresource
developeremail
developerid
appgroupname
consumerkey apiresource
app appid
appname developeremail
developerid
appgroupname
consumerkey
authorizationcode authorizationcode
appgroupname appid
appgroupname
consumerkey
consumerkey
consumerkey consumerkey
consumerkey_scope consumerkey
developer appid
consumerkey
developeremail
developerid
requesttoken requesttoken consumerkey
verifier verifier

דוגמה ל-XML של פרופיל ישות

כדי לאחזר את הערך של פרופיל הישות שרוצים באמצעות XPath, צריך לדעת משהו על המבנה של ה-XML של הפרופיל. כדי לראות דוגמה למבנה, משתמשים בקריאה ל-Apigee API כדי לקבל XML עבור הישות הרצויה. פרטים נוספים זמינים בהפניית Apigee API.

בקטעים הבאים מופיע קוד לקריאות API, יחד עם דוגמה ל-XML מהקריאה.

אפליקציות

curl https://apigee.googleapis.com/v1/organizations/$ORG/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

אפשר לעיין גם במאמר Get app by app ID (קבלת אפליקציה לפי מזהה האפליקציה) בהפניית Apigee API.

או:

$ curl https://apigee.googleapis.com/v1/organizations/$ORG/developers/$DEVELOPER_EMAIL/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

אפשר גם לעיין במאמר Get developer app details בהפניית Apigee API.

פרופיל לדוגמה:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<App name="thomas-app">
    <AccessType>read</AccessType>
    <ApiProducts/>
    <Credentials>
        <Credential>
            <Attributes/>
            <ConsumerKey>wrqOOOiPArFI0WRoB1gAJMRbOguekJ5w</ConsumerKey>
            <ConsumerSecret>WvOhDrJ8m6kzz7Ni</ConsumerSecret>
            <ApiProducts>
                <ApiProduct>
                    <Name>FreeProduct</Name>
                    <Status>approved</Status>
                </ApiProduct>
            </ApiProducts>
            <Scopes/>
            <Status>approved</Status>
        </Credential>
    </Credentials>
    <AppFamily>default</AppFamily>
    <AppId>ab308c13-bc99-4c50-8434-0e0ed1b86075</AppId>
    <Attributes>
        <Attribute>
            <Name>DisplayName</Name>
            <Value>Tom's Weather App</Value>
        </Attribute>
    </Attributes>
    <CallbackUrl>http://tom.app/login</CallbackUrl>
    <CreatedAt>1362502872727</CreatedAt>
    <CreatedBy>admin@apigee.com</CreatedBy>
    <DeveloperId>PFK8IwOeAOW01JKA</DeveloperId>
    <LastModifiedAt>1362502872727</LastModifiedAt>
    <LastModifiedBy>admin@apigee.com</LastModifiedBy>
    <Scopes/>
    <Status>approved</Status>
</App>

מוצר API

curl https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

אפשר לעיין גם במאמר Get API product בהפניית API של Apigee.

דוגמה ל-XPath, שמאחזר את משאב ה-API השני (URI) ממוצר ה-API שנקרא weather_free:

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

דוגמה לפרופיל שמוחזר כ-XML:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ApiProduct name="weather_free">
    <ApiResources>
        <ApiResource>/forecastrss, /reports</ApiResource>
    </ApiResources>
    <ApprovalType>auto</ApprovalType>
    <Attributes>
        <Attribute>
            <Name>description</Name>
            <Value>Introductory API Product</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.interval</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.limit</Name>
            <Value>1</Value>
        </Attribute>
        <Attribute>
            <Name>developer.quota.timeunit</Name>
            <Value>minute</Value>
        </Attribute>
        <Attribute>
            <Name>servicePlan</Name>
            <Value>Introductory</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1355847839224</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <Description>Free API Product</Description>
    <DisplayName>Free API Product</DisplayName>
    <Environments/>
    <LastModifiedAt>1355847839224</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
    <Proxies/>
    <Scopes/>
</ApiProduct>

טוקן צרכן

curl https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL/apps/$APP/keys/$KEY \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

אפשר גם לעיין במאמר קבלת פרטים על מפתח של אפליקציה למפתחים ב-Apigee הפניית API.

דוגמה ל-XPath:

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

פרופיל לדוגמה:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Credential>
    <Attributes/>
    <ConsumerKey>XLotL3PRxNkUGXhGAFDPOr6fqtvAhuZe</ConsumerKey>
    <ConsumerSecret>iNUyEaOOh96KR3YL</ConsumerSecret>
    <ApiProducts>
        <ApiProduct>
            <Name>weather_free</Name>
            <Status>approved</Status>
        </ApiProduct>
    </ApiProducts>
    <Scopes/>
    <Status>approved</Status>
</Credential>

מפתח

curl https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

אפשר לעיין גם במאמר Get developer בהפניית Apigee API.

דוגמה ל-XPath:

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
 
/Developer/Email/text()

פרופיל לדוגמה:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developer>
    <Apps>
        <App>weatherappx</App>
        <App>weatherapp</App>
    </Apps>
    <Email>ntesla@theramin.com</Email>
    <DeveloperId>4Y4xd0KRZ1wmHJqu</DeveloperId>
    <FirstName>Nikola</FirstName>
    <LastName>Tesla</LastName>
    <UserName>theramin</UserName>
    <OrganizationName>apigee-pm</OrganizationName>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>project_type</Name>
            <Value>public</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349797040634</CreatedAt>
    <CreatedBy>rsaha@apigee.com</CreatedBy>
    <LastModifiedAt>1349797040634</LastModifiedAt>
    <LastModifiedBy>rsaha@apigee.com</LastModifiedBy>
</Developer>

משתנים בתהליך

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

לדוגמה, אם מופעלת מדיניות AccessEntity עם שם GetDeveloper, הפרופיל מאוחסן במשתנה בשם AccessEntity.GetDeveloper. לאחר מכן אפשר לנתח את הפרופיל באמצעות XPath שמוגדר במדיניות ExtractVariables שמציינת את AccessEntity.GetDeveloper כמקור שלה.

הפניה לשגיאה

מידע נוסף בנושא זמין במאמרים מה צריך לדעת על שגיאות שקשורות למדיניות וטיפול בשגיאות.

שגיאות זמן ריצה

אין.

שגיאות בהטמעה

שם השגיאה מחרוזת שגיאה סטטוס HTTP מתרחש כאשר
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] לא רלוונטי סוג הישות שבו משתמשים חייב להיות אחד מהסוגים הנתמכים.

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