מדיניות AccessEntity

אתם צופים במסמכי התיעוד של Apigee Edge.
כדאי לעיין במסמכי התיעוד של Apigee X. מידע

מה

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

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

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

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

דוגמאות

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

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

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

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

<AccessEntity name="GetDeveloperProfile">
  <!-- This is the type entity whose profile we need to pull from the Edge 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> כדי להוסיף תווית למדיניות עורך ה-Proxy של ממשק המשתמש לניהול בעל שם אחר בשפה טבעית.

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

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

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

 false אופציונלי
enabled

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

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

 true אופציונלי
async

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

 false הוצא משימוש

&lt;DisplayName&gt; רכיב

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

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

לא רלוונטי

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

אלמנט <EntityIdentifier>

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

<EntityIdentifier ref="value_variable" type="identifier_type"/>

ברירת מחדל

לא רלוונטי

נוכחות

חובה

סוג

מחרוזת

מאפיינים

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

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

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

דוגמה

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

אלמנט <EntityType>

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

<EntityType  value="entity_type"/>

ברירת מחדל

לא רלוונטי

נוכחות

חובה

סוג

מחרוזת

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

מאפיינים

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

רכיב <SecondaryIdentifier>

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

<SecondaryIdentifier ref="value_variable" type="identifier_type"/>

ברירת מחדל

לא רלוונטי

נוכחות

אופציונלי

סוג

מחרוזת

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

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

מאפיינים

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

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

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

דוגמה

<?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
companyname
consumerkey apiresource
app appid
appname developeremail
developerid
companyname
consumerkey
authorizationcode authorizationcode
company appid
company
consumerkey
companydeveloper companyname
consumerkey consumerkey
consumerkey_scope consumerkey
developer appid
consumerkey
developeremail
developerid
requesttoken requesttoken consumerkey
verifier verifier

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

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

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

אפליקציות

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u email:password

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

או:

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name} \
-u email:password

אפשר לעיין גם במאמר Get Developer App Details (קבלת פרטים על אפליקציה למפתחים) במאמרי העזרה של ה-API של Edge Management.

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

<?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  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password

אפשר גם לעיין במאמר Get API Product במאמרי העזרה של ה-API של Edge Management.

דוגמה ל-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   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u email:password

אפשר לעיין גם במאמר Get Company Details (קבלת פרטי החברה) במאמר בנושא Edge Management API Reference.

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Company name="theramin">
    <Apps/>
    <DisplayName>Theramin Corporation</DisplayName>
    <Organization>apigee-pm</Organization>
    <Status>active</Status>
    <Attributes>
        <Attribute>
            <Name>billing_code</Name>
            <Value>13648765</Value>
        </Attribute>
    </Attributes>
    <CreatedAt>1349208631291</CreatedAt>
    <CreatedBy>andrew@apigee.com</CreatedBy>
    <LastModifiedAt>1349208631291</LastModifiedAt>
    <LastModifiedBy>andrew@apigee.com</LastModifiedBy>
</Company>

מפתח בחברה

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name}/developers/{developer_name} \
-u email:password

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

מפתח יצרן

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email}/apps/{app_name}/keys/{consumer_key} \
-u email:password

אפשר גם לעיין במאמר Get Key Details for a Developer App (קבלת פרטים על מפתח של אפליקציה למפתחים) בחומר העזר בנושא Edge Management 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 -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password

אפשר לעיין גם במאמר Get Developer במאמרי העזרה של ה-API של Edge Management.

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

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

הפניה לשגיאה

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

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

ללא.

שגיאות בפריסה

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

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