AccessEntity 政策

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件
資訊

優勢

這個外掛程式能從 Apigee Edge 資料儲存庫擷取您指定的實體設定檔。政策會將設定檔放置在名稱格式為 AccessEntity.{policy_name} 的變數中。您可以使用 AccessEntity 存取下列實體的設定檔:

  • 應用程式
  • API 產品
  • 公司
  • 公司開發人員
  • 消費者金鑰
  • 開發人員

AccessEntity 政策可做為政策執行階段資料庫查詢。您可以使用這項政策傳回的設定檔資訊,啟用動態行為,例如條件式端點轉送、流程執行、政策強制執行。

請使用 AccessEntity 政策,以 XML 格式取得實體設定檔資料,並將其放入變數中。您可以指定實體類型和一或多個 ID,指定要取得的實體。稍後,您可以在另一項政策中使用其他政策,例如 ExtractVariables 政策AssignMessage 政策

範例

以下範例顯示 AccessEntity 可與 ExtractVariablesAssignMessage 政策搭配使用,藉此擷取開發人員的電子郵件並新增至 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 先前設定的 AccessEntity.GetDeveloperProfile 變數中擷取一個值。

請注意,擷取的值會在 XMLPayload 元素中指定為 XPath 運算式。擷取的值會放在 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> 元素,在管理 UI Proxy 編輯器中使用不同的自然語言名稱為政策加上標籤。

不適用 需要
continueOnError

如果設為 false,即可在政策失敗時傳回錯誤。大部分政策都是預期中的行為。

設為 true,即可在政策失敗後繼續執行資料流。

false 選用
enabled

如要強制執行政策,請設為 true

設為 false 即可停用這項政策。即使政策仍附加在流程中,系統也不會強制執行政策。

true 選用
async

此屬性已淘汰。

false 已淘汰

<DisplayName> 元素

除了 name 屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。

<DisplayName>Policy Display Name</DisplayName>
預設

不適用

如果省略這個元素,系統會使用政策的 name 屬性值。

存在必要性 選用
類型 字串

<EntityIdentifier> 元素

指定要取得的特定實體 (屬於 EntityType 中指定的類型)。

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

預設

不適用

外觀狀態

需要

類型

字串

屬性

屬性 說明 預設 存在必要性 類型
參考資料

提供 ID 來源的變數,例如 request.queryparam.apikey

不適用 這是必填欄位。 字串
類型 由 ref 屬性中變數填入的類型,例如 consumerkey。如需值的清單,請參閱實體類型和 ID 這是必填欄位。 字串

範例

<?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 元素指定所需的指定類型實體。如需實體類型的參考資料,請參閱實體類型和 ID

屬性

屬性 說明 預設 存在必要性 類型
支援的實體類型之一。如需清單,請參閱「實體類型和 ID」。 無。 這是必填欄位。 字串

<SecondaryIdentifier> 元素

搭配 EntityIdentifier 使用,可指定值以識別特定 EntityType 的所需執行個體。

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

預設

不適用

外觀狀態

選用

類型

字串

僅指定 EntityIdentifier 時使用 SecondaryIdentifier,不保證您能獲得單一實體。詳情請參閱「使用次要 ID 縮小結果範圍」一文。

不支援使用多個 SecondaryIdentifier 元素。

屬性

屬性 說明 預設 存在必要性 類型
參考資料

提供 ID 來源的變數,例如 request.queryparam.apikey

不適用 這是必填欄位。 字串
類型 由 ref 屬性中變數填入的類型,例如 consumerkey。如需值的清單,請參閱實體類型和 ID 這是必填欄位。 字串

範例

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

使用須知

利用次要 ID 縮小結果範圍

對某些實體提供一個 ID 可能不足以取得您想要的實體。在這種情況下,您可以使用次要 ID 縮小結果範圍。

首先,可能的廣泛政策設定可能如下所示:

<?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 產品建立關聯,因此只使用應用程式 ID 可能無法傳回您需要的 API 產品 (您可以只取得多個相符產品的第一個項目)。

如要取得更準確的結果,您可以使用 SecondaryIdentifier。舉例來說,您可能在流程中使用 appnamedeveloperid 變數,因為根據預設,系統會在 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>

支援的實體類型和 ID

AccessEntity 支援下列實體類型和 ID,

實體類型值 EntityIdentifier 類型 SecondaryIdentifier 類型
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 的結構。舉例來說,結構的範例可以使用 Management 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 參考資料中的「透過應用程式 ID 在機構中取得應用程式」。

或:

$ 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

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

另請參閱 Edge Management API 參考資料中的「取得 API 產品」一節。

XPath 範例會從名為 weather_free 的 API 產品擷取第二個 API 資源 (URI):

/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

另請參閱 Edge Management API 參考資料中的「取得公司詳細資料」。

範例設定檔:

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

另請參閱 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

另請參閱 Edge Management 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 政策中指定的實體設定檔時,系統會將 XML 格式的設定檔物件新增至訊息結構定義中,做為變數。可存取這類變數,就和存取變數名稱一樣,也能參照變數名稱。使用者提供的 AccessEntity 政策名稱會設為變數名稱的變數前置字串。

舉例來說,如果執行名稱為 GetDeveloper 的 AccessEntity 政策,則 XML 格式設定檔會儲存在名為 AccessEntity.GetDeveloper 的變數中。接著,在指定 AccessEntity.GetDeveloper 做為來源的「ExtractVariables」政策中所定義的 XPath,即可剖析 XML 格式的設定檔。

錯誤參考資料

如需相關資訊,請參閱政策錯誤須知處理錯誤

執行階段錯誤

無。

部署錯誤

錯誤名稱 錯誤字串 HTTP 狀態 發生時機
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] 不適用 使用的實體類型必須是支援的類型之一。

相關主題