您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊
優勢
這個外掛程式能從 Apigee Edge 資料儲存庫擷取您指定的實體設定檔。政策會將設定檔放置在名稱格式為 AccessEntity.{policy_name}
的變數中。您可以使用 AccessEntity
存取下列實體的設定檔:
- 應用程式
- API 產品
- 公司
- 公司開發人員
- 消費者金鑰
- 開發人員
AccessEntity
政策可做為政策執行階段資料庫查詢。您可以使用這項政策傳回的設定檔資訊,啟用動態行為,例如條件式端點轉送、流程執行、政策強制執行。
請使用 AccessEntity
政策,以 XML 格式取得實體設定檔資料,並將其放入變數中。您可以指定實體類型和一或多個 ID,指定要取得的實體。稍後,您可以在另一項政策中使用其他政策,例如 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
先前設定的 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 |
政策的內部名稱。 您也可以選擇使用 |
不適用 | 需要 |
continueOnError |
如果設為 設為 |
false | 選用 |
enabled |
如要強制執行政策,請設為 設為 |
true | 選用 |
async |
此屬性已淘汰。 |
false | 已淘汰 |
<DisplayName> 元素
除了 name
屬性外,您還可以使用不同的自然語言名稱,在管理 UI Proxy 編輯器中為政策加上標籤。
<DisplayName>Policy Display Name</DisplayName>
預設 |
不適用 如果省略這個元素,系統會使用政策的 |
---|---|
存在必要性 | 選用 |
類型 | 字串 |
<EntityIdentifier> 元素
指定要取得的特定實體 (屬於 EntityType 中指定的類型)。
<EntityIdentifier ref="value_variable" type="identifier_type"/>
預設 |
不適用 |
外觀狀態 |
需要 |
類型 |
字串 |
屬性
屬性 | 說明 | 預設 | 存在必要性 | 類型 |
---|---|---|---|---|
參考資料 |
提供 ID 來源的變數,例如 |
不適用 | 這是必填欄位。 | 字串 |
類型 | 由 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 來源的變數,例如 |
不適用 | 這是必填欄位。 | 字串 |
類型 | 由 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
。舉例來說,您可能在流程中使用 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>
支援的實體類型和 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] |
不適用 | 使用的實體類型必須是支援的類型之一。 |
相關主題
ExtractVariables
:ExtractVariables 政策AssignMessage
:AssignMessage 政策