AccessEntity 政策

本頁適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

存取實體政策圖示

結果

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

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

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

使用 AccessEntity 政策取得實體設定檔資料，並將其以 XML (或 Apigee hybrid 中的 JSON) 格式放入變數。請指定實體類型和一或多個 ID，藉此識別要取得的實體，這些 ID 會指定您要取得的該類型實體。之後，您可以在其他政策中使用其他政策擷取實體設定檔資料，例如 ExtractVariables 政策或 AssignMessage 政策。

這項政策是可擴充的政策，視您的 Apigee 授權而定，使用這項政策可能會產生費用或使用量影響。如要瞭解政策類型和使用相關性，請參閱「政策類型」。

從 AccessEntity 存取 AppGroups 實體

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

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

範例

以下範例顯示 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，即使政策失敗，流程執行作業仍會繼續進行。另請參閱：

 false 選用
enabled

設為 true 即可強制執行政策。

設為 false 即可關閉政策。即使政策仍附加至流程中，也不會強制執行。

 是 選用
async

此屬性已淘汰。

 false 已淘汰

<DisplayName> 元素

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

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

不適用

如果省略這個元素，系統會使用政策的 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> 元素

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

<OutputFormat>XML</OutputFormat>
預設

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 縮小結果範圍。

您可能會先設定較廣泛的政策，如下所示：

<?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 產品 (您可能只會取得多個相符產品中的第 1 個)。

如要取得更精確的結果，您可以改用 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] 不適用 使用的實體類型必須是支援的類型之一。

相關主題