מדיניות AccessEntity

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

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

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

מדיניות AccessEntity מאחזרת פרופילים של ישויות שאתם מציינים ממאגר הנתונים של Apigee. המדיניות מציבה את הפרופיל במשתנה שהשם שלו בנוי בפורמט AccessEntity.{policy_name}. אפשר להשתמש ב-AccessEntity כדי לגשת לפרופילים של הישויות הבאות:

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

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

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

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

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

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

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

דוגמאות

בדוגמאות הבאות מוצג שימוש ב-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"

אפשר לעיין גם במאמר קבלת אפליקציה לפי מזהה האפליקציה בהפניית 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"

אפשר לעיין גם במאמר קבלת פרטי האפליקציה של מפתחים בהפניית 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"

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

דוגמה ל-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"

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

משתני Flow

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

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

הפניה לשגיאה

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

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

אין.

שגיאות פריסה

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

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