本頁面由 Cloud Translation API 翻譯而成。

AccessEntity 政策

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

存取實體政策圖示

結果

從 Apigee 資料存放區擷取您指定的實體設定檔。這項政策會將設定檔放在變數中，變數名稱的格式為 AccessEntity.{policy_name}。您可以使用 AccessEntity 存取下列實體的設定檔：

應用程式
API 產品
消費端金鑰
開發人員

AccessEntity政策的作用是根據政策查詢執行階段資料庫。您可以使用這項政策傳回的設定檔資訊啟用動態行為，例如條件式端點路徑、流程執行、政策強制執行。

使用 AccessEntity 政策以 XML 格式 (或 Apigee hybrid 中的 JSON 格式) 取得實體設定檔資料，並將資料放入變數中。指定實體型別和一或多個 ID，找出要取得的實體。稍後，您可以在其他政策中，使用 ExtractVariables 政策或 AssignMessage 政策等其他政策，擷取實體設定檔資料。

這項政策是可擴充政策，使用這項政策可能會產生費用或影響用量，具體情況取決於您的 Apigee 授權。如要瞭解政策類型和使用方式的影響，請參閱「政策類型」。

從 `AccessEntity` 存取 AppGroups 實體

您也可以使用 AccessEntity 擷取 AppGroup 實體。如要瞭解相關實體，請參閱「支援的實體類型和 ID」。

如要瞭解 AppGroup 和支援的功能，請參閱「使用 AppGroup 管理應用程式擁有權」。

範例

下列範例顯示 AccessEntity 如何搭配 ExtractVariables 和 AssignMessage 政策，擷取開發人員的電子郵件地址並新增至 HTTP 標頭。

取得開發人員電子郵件地址，以用於其他政策

設定 AccessEntity 政策，指定要從 Apigee 取得哪個實體設定檔，以及設定檔資料的放置位置。

在下列範例中，政策會使用做為查詢參數傳遞的 API 金鑰，取得 developer 實體設定檔，以識別開發人員。設定檔會放在變數中，變數名稱的格式為 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 先前設定的 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 代理程式編輯器中為政策加上不同、自然語言的名稱。	不適用	必填
`continueOnError`	將其設為 `false`，即可在政策失敗時傳回錯誤。這是大多數政策的預期行為。將其設為 `true`，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：錯誤規則僅會在錯誤狀態下觸發 (關於 continueOnError) 處理目前流程中的錯誤	false	選用
`enabled`	設為 `true` 即可強制執行政策。設為 `false` 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。	是	選用
`async`	此屬性已淘汰。	false	已淘汰

<DisplayName> 元素

除了 name 屬性之外，您也可以在管理 UI 代理程式編輯器中使用不同的自然語言名稱標示政策。

<DisplayName>Policy Display Name</DisplayName>

預設

預設	不適用如果省略這個元素，系統會使用政策的 `name` 屬性值。
存在必要性	選用
類型	字串

不適用

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

存在必要性選用

類型字串

<EntityIdentifier> 元素

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

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

預設	不適用
存在必要性	必填
類型	字串

屬性

屬性	說明	預設	存在必要性	類型
ref	提供 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>

<EntityType> 元素

指定要從資料存放區擷取的實體類型。

<EntityType  value="entity_type"/>

預設	不適用
存在必要性	必填
類型	字串

使用 EntityIdentifier 元素指定要使用的指定類型實體。如需實體類型參考資料，請參閱「支援的實體類型和 ID」。

屬性

屬性	說明	預設	存在必要性	類型
值	其中一種支援的實體類型。如需清單，請參閱「支援的實體類型和 ID」。	無	必填	字串

<OutputFormat> 元素

注意： <OutputFormat> 僅適用於混合式環境，混合式 v1.4 以上版本皆可使用。

指定 AccessEntity 政策傳回的格式：XML 或 JSON。

<OutputFormat>XML</OutputFormat>

預設	XML 如果省略這個元素，值會預設為 XML。
存在必要性	選用
類型	字串 (XML 或 JSON)

預設

XML

如果省略這個元素，值會預設為 XML。

存在必要性

選用

類型

字串 (XML 或 JSON)

<SecondaryIdentifier> 元素

與 EntityIdentifier 搭配使用，指定值來識別指定 EntityType 的所需例項。

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

預設	不適用
存在必要性	選用
類型	字串

指定 EntityIdentifier 時使用 SecondaryIdentifier 並不保證會取得單一實體。詳情請參閱「使用次要 ID 縮小結果範圍」。

系統不支援使用多個 SecondaryIdentifier 元素。

屬性

屬性	說明	預設	存在必要性	類型
ref	提供 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 縮小結果範圍。

注意：如果特定 EntityIdentifier 和 SecondaryIdentifier 組合有多個相符項目，系統會將第一個相符項目填入流程。舉例來說，假設您想使用應用程式 ID 取得 API 產品設定檔。

您可能需要先設定較為寬鬆的政策，如下所示：

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

EntityType 值	EntityIdentifier 類型	SecondaryIdentifier 類型
`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 參考資料中的「依應用程式 ID 取得應用程式」。

或：

$ 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"

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

流程變數

系統擷取 AccessEntity 政策中指定的實體設定檔時，設定檔物件會以變數形式新增至訊息環境。您可以參照變數名稱，存取任何其他變數。系統會將使用者提供的「AccessEntity」政策名稱設為變數名稱的變數前置字元。

舉例來說，如果執行名稱為 GetDeveloper 的 AccessEntity 政策，設定檔就會儲存在名為 AccessEntity.GetDeveloper 的變數中。然後，您可以使用 ExtractVariables 政策中定義的 XPath 剖析設定檔，該政策會將 AccessEntity.GetDeveloper 指定為來源。

錯誤參考資料

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

執行階段錯誤

無。

部署錯誤

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

AccessEntity 政策 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

結果

從 AccessEntity 存取 AppGroups 實體

範例

取得開發人員電子郵件地址，以用於其他政策

元素參考資料

<AccessEntity> 屬性

<DisplayName> 元素

<EntityIdentifier> 元素

屬性

範例

<EntityType> 元素

屬性

<OutputFormat> 元素

<SecondaryIdentifier> 元素

屬性

範例

使用須知

使用次要 ID 縮小結果範圍

支援的實體類型和 ID

實體設定檔 XML 範例

應用程式

API 產品

消費端金鑰

開發人員

流程變數

錯誤參考資料

執行階段錯誤

部署錯誤

相關主題

AccessEntity 政策

從 `AccessEntity` 存取 AppGroups 實體