AccessEntity 政策

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

結果

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

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

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

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

範例

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

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

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

在下列範例中，政策會使用做為查詢參數傳遞的 API 金鑰，識別開發人員並取得 developer 實體設定檔。設定檔會放在變數中，變數名稱的格式為 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 設定。

請注意，擷取的值是在 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> 元素，為政策加上標籤： 管理使用者介面 Proxy 編輯器，使用不同的自然語言名稱。

 不適用 必填
continueOnError

如果設為「false」，系統會在政策失敗時傳回錯誤。這是可預期的情況 大多數政策的行為

如果設為 true，即使政策已發生，流程執行作業仍會繼續執行 失敗。

 false 選用
enabled

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

設為 false 即可停用政策。這項政策不會 仍會強制執行 政策。

 true 選用
async

此屬性已淘汰。

 false 已淘汰

&lt;DisplayName&gt;元素

除 name 屬性外，一併使用 管理 UI Proxy 編輯器，使用不同的自然語言名稱。

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

不適用

如果省略這個元素，政策的 name 屬性值會是

存在必要性 選用
類型 字串

<EntityIdentifier> 元素

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

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

預設

N/A

外觀狀態

必填

類型

字串

屬性

屬性 說明 預設 存在必要性 類型
ref

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

 N/A 必填。 字串
類型 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"/>

預設

N/A

外觀狀態

必填

類型

字串

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

屬性

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

<SecondaryIdentifier> 元素

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

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

預設

N/A

外觀狀態

選用

類型

字串

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

不支援使用多個 SecondaryIdentifier 元素。

屬性

屬性 說明 預設 存在必要性 類型
ref

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

 N/A 必填。 字串
類型 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。

EntityType 值 實體 ID 類型 次要 ID 類型
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 管理 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 管理 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 管理 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 管理 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 管理 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 管理 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 的變數中。接著，您可以使用 ExtractVariables 政策中定義的 XPath 剖析 XML 格式的設定檔，並將 AccessEntity.GetDeveloper 指定為來源。

錯誤參考資料

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

執行階段錯誤

無。

部署錯誤

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

相關主題