Chính sách AccessEntity

Bạn đang xem tài liệu về Apigee Edge.
Truy cập vào tài liệu Apigee X. thông tin

Nội dung

Truy xuất các hồ sơ thực thể mà bạn chỉ định từ kho dữ liệu Apigee Edge. Chính sách này đặt hồ sơ vào một biến có tên theo định dạng AccessEntity.{policy_name}. Bạn có thể sử dụng AccessEntity để truy cập vào hồ sơ của các thực thể sau:

  • Ứng dụng
  • Sản phẩm API
  • Công ty
  • Nhà phát triển của công ty
  • Khoá dành cho người dùng
  • Nhà phát triển

Chính sách AccessEntity hoạt động như một hoạt động tra cứu cơ sở dữ liệu thời gian chạy dựa trên chính sách. Bạn có thể sử dụng thông tin hồ sơ do chính sách này trả về để bật hành vi động, chẳng hạn như định tuyến điểm cuối có điều kiện, thực thi luồng, thực thi chính sách.

Bạn sử dụng chính sách AccessEntity để lấy dữ liệu hồ sơ thực thể dưới dạng XML và đưa dữ liệu đó vào một biến. Bạn xác định thực thể cần lấy bằng cách chỉ định một loại thực thể và một hoặc nhiều giá trị nhận dạng chỉ định thực thể nào thuộc loại đó mà bạn muốn. Sau đó, trong một chính sách khác, bạn có thể truy xuất dữ liệu hồ sơ thực thể bằng một chính sách khác, chẳng hạn như chính sách ExtractVariables hoặc chính sách AssignMessage.

Mẫu

Các mẫu sau đây cho thấy AccessEntity được dùng kết hợp với các chính sách ExtractVariables và AssignMessage để trích xuất email của nhà phát triển và thêm email đó vào tiêu đề HTTP.

Lấy email của nhà phát triển để sử dụng trong các chính sách khác

Thiết lập chính sách AccessEntity để chỉ định hồ sơ thực thể cần lấy từ Edge, cũng như vị trí đặt dữ liệu hồ sơ.

Trong ví dụ sau, chính sách này sẽ nhận được hồ sơ thực thể developer, bằng cách sử dụng khoá API được truyền dưới dạng tham số truy vấn để xác định nhà phát triển. Hồ sơ được đặt trong một biến có tên theo dạng AccessEntity.{policy_name}. Vì vậy, biến do chính sách này đặt sẽ là 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>

Sử dụng một chính sách khác để truy xuất giá trị hồ sơ thực thể từ biến do AccessEntity đặt.

Trong ví dụ sau, một chính sách ExtractVariables sẽ truy xuất một giá trị từ biến AccessEntity.GetDeveloperProfile mà AccessEntity đã đặt trước đó.

Xin lưu ý rằng giá trị được truy xuất được chỉ định dưới dạng một biểu thức XPath trong phần tử XMLPayload. Giá trị được trích xuất sẽ được đặt trong biến 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>

Chính sách AssignMessage sau đây sẽ truy xuất email của nhà phát triển do chính sách ExtractVariables đặt.

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

Tài liệu tham khảo về phần tử

Cấu trúc cơ bản của chính sách AccessEntity là:

<AccessEntity name="policy_name">
  <EntityType  value="entity_type"/>
  <EntityIdentifier ref="entity_identifier" type="identifier_type"/> 
  <SecondaryIdentifier ref="secondary_identifier" type="identifier_type"/>
</AccessEntity>

Bạn có thể truy cập vào nhiều thực thể thuộc cùng một loại bằng cách nhóm chúng trong phần tử 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>

Thuộc tính <AccessEntity>

<AccessEntity async="false" continueOnError="false" enabled="true" name="policy_name">

Bảng sau đây mô tả những thuộc tính chung cho tất cả phần tử mẹ của chính sách:

Thuộc tính Mô tả Mặc định Sự hiện diện
name

Tên nội bộ của chính sách. Giá trị của thuộc tính name có thể chứa chữ cái, số, dấu cách, dấu gạch nối, dấu gạch dưới và dấu chấm. Giá trị này không được vượt quá 255 ký tự.

(Không bắt buộc) Bạn có thể dùng phần tử <DisplayName> để gắn nhãn chính sách trong trình chỉnh sửa proxy giao diện người dùng quản lý bằng tên ngôn ngữ tự nhiên khác.

 Không áp dụng Bắt buộc
continueOnError

Đặt thành false để trả về lỗi khi chính sách không thành công. Điều này là dự kiến đối với hầu hết các chính sách.

Đặt thành true để tiếp tục thực thi luồng ngay cả sau khi có chính sách không thành công.

 false Không bắt buộc
enabled

Hãy đặt thành true để thực thi chính sách này.

Đặt thành false để tắt chính sách này. Chính sách này sẽ không được thực thi ngay cả khi luồng đó vẫn được liên kết với một luồng.

 đúng Không bắt buộc
async

Thuộc tính này không được dùng nữa.

 false Không được dùng nữa

&lt;DisplayName&gt; phần tử

Hãy sử dụng cùng với thuộc tính name để gắn nhãn chính sách trong phần trình chỉnh sửa proxy giao diện người dùng quản lý có tên ngôn ngữ tự nhiên khác.

<DisplayName>Policy Display Name</DisplayName>
Mặc định

Không áp dụng

Nếu bạn bỏ qua phần tử này, giá trị của thuộc tính name của chính sách sẽ là đã sử dụng.
Sự hiện diện Không bắt buộc
Loại Chuỗi

Phần tử <EntityIdentifier>

Chỉ định thực thể cụ thể (thuộc loại được cung cấp trong EntityType) để nhận.

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

Mặc định

Không áp dụng

Sự hiện diện

Bắt buộc

Loại

Chuỗi

Thuộc tính

Thuộc tính Mô tả Mặc định Tỷ lệ hiển thị Loại
ref

Biến cung cấp nguồn của giá trị nhận dạng, chẳng hạn như request.queryparam.apikey.

 Không áp dụng Bắt buộc. Chuỗi
loại Loại được biến điền sẵn trong thuộc tính ref, chẳng hạn như consumerkey. Hãy xem phần Các loại và giá trị nhận dạng thực thể để biết danh sách các giá trị. Bắt buộc. Chuỗi

Ví dụ

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

Phần tử <EntityType>

Chỉ định loại thực thể cần truy xuất từ kho dữ liệu.

<EntityType  value="entity_type"/>

Mặc định

Không áp dụng

Sự hiện diện

Bắt buộc

Loại

Chuỗi

Sử dụng phần tử EntityIdentifier để chỉ định thực thể thuộc loại đã cho mà bạn muốn. Để tham khảo các loại thực thể, hãy xem bài viết Các loại thực thể và giá trị nhận dạng.

Thuộc tính

Thuộc tính Mô tả Mặc định Tỷ lệ hiển thị Loại
value Một trong những loại thực thể được hỗ trợ. Hãy xem phần Loại thực thể và giá trị nhận dạng để biết danh sách. Không có. Bắt buộc. Chuỗi

Phần tử <SecondaryIdentifier>

Kết hợp với EntityIdentifier, chỉ định một giá trị để xác định phiên bản mong muốn của EntityType đã cho.

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

Mặc định

Không áp dụng

Sự hiện diện

Không bắt buộc

Loại

Chuỗi

Sử dụng SecondaryIdentifier khi chỉ định chỉ một EntityIdentifier sẽ không đảm bảo rằng bạn nhận được một thực thể duy nhất. Hãy xem phần Thu hẹp kết quả bằng giá trị nhận dạng phụ để biết thêm thông tin.

Không hỗ trợ việc sử dụng nhiều phần tử SecondaryIdentifier.

Thuộc tính

Thuộc tính Mô tả Mặc định Tỷ lệ hiển thị Loại
ref

Biến cung cấp nguồn của giá trị nhận dạng, chẳng hạn như request.queryparam.apikey.

 Không áp dụng Bắt buộc. Chuỗi
loại Loại được biến điền sẵn trong thuộc tính ref, chẳng hạn như consumerkey. Hãy xem phần Các loại và giá trị nhận dạng thực thể để biết danh sách các giá trị. Bắt buộc. Chuỗi

Ví dụ

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

Lưu ý về cách sử dụng

Thu hẹp kết quả bằng giá trị nhận dạng phụ

Đối với một số thực thể, việc cung cấp một giá trị nhận dạng có thể không đủ cụ thể để nhận được thực thể bạn muốn. Trong những trường hợp đó, bạn có thể sử dụng một giá trị nhận dạng phụ để thu hẹp kết quả.

Cấu hình chính sách đầu tiên (có thể là cấu hình chính sách chung) của bạn có thể có dạng như sau:

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

Vì một ứng dụng có thể được liên kết với nhiều sản phẩm API, nên chỉ sử dụng mã nhận dạng ứng dụng có thể không trả về sản phẩm API mà bạn muốn (bạn chỉ có thể nhận được sản phẩm đầu tiên trong số nhiều sản phẩm trùng khớp).

Thay vào đó, để nhận được kết quả chính xác hơn, bạn có thể sử dụng SecondaryIdentifier. Ví dụ: bạn có thể có các biến appname và developerid trong luồng vì các biến này được điền sẵn theo mặc định trong quá trình trao đổi OAuth 2.0. Bạn có thể sử dụng các giá trị của những biến đó trong chính sách AccessEntity để nhận thông tin chi tiết về hồ sơ trên ứng dụng yêu cầu.

Cấu hình chính sách cụ thể hơn của bạn có thể có dạng như sau:

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

Các loại thực thể và giá trị nhận dạng được hỗ trợ

AccessEntity hỗ trợ các loại thực thể và giá trị nhận dạng sau đây.

Giá trị EntityType Các loại EntityIdentifier Loại 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

Ví dụ về tệp XML hồ sơ thực thể

Để truy xuất giá trị hồ sơ thực thể mà bạn muốn bằng XPath, bạn cần biết một số thông tin về cấu trúc XML của hồ sơ. Để xem ví dụ về cấu trúc, hãy dùng một lệnh gọi API quản lý để lấy XML cho thực thể bạn muốn. Để biết thông tin chi tiết, hãy tham khảo tài liệu tham khảo về API quản lý.

Các phần sau đây bao gồm mã cho các lệnh gọi API, cùng với ví dụ về XML từ lệnh gọi.

Ứng dụng

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u email:password

Xem thêm phần Lấy ứng dụng trong một tổ chức theo mã ứng dụng trong tài liệu tham khảo về Edge Management API.

hoặc:

$ 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

Xem thêm phần Lấy thông tin chi tiết về ứng dụng dành cho nhà phát triển trong tài liệu tham khảo API quản lý Edge.

Hồ sơ mẫu:

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

Sản phẩm API

$ curl  -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts/{apiproduct_name} \
-u email:password

Xem thêm phần Nhận sản phẩm API trong tài liệu tham khảo API quản lý Edge.

XPath mẫu, truy xuất tài nguyên API thứ hai (URI) từ sản phẩm API có tên weather_free:

/ApiProduct['@name=weather_free']/ApiResources/ApiResource[1]/text()

Hồ sơ mẫu được trả về dưới dạng 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>

Công ty

$ curl   -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/companies/{company_name} \
-u email:password

Xem thêm phần Lấy thông tin chi tiết về công ty trong tài liệu tham khảo về Edge Management API.

Hồ sơ mẫu:

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

Nhà phát triển của công ty

$ 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

Hồ sơ mẫu:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Developers>
    <Developer>
        <Email>ntesla@theramin.com</Email>
        <Role>developer</Role>
    </Developer>
</Developers>

Khoá dành cho người dùng

$ 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

Xem thêm phần Lấy thông tin chi tiết về khoá cho ứng dụng nhà phát triển trong tài liệu tham khảo API quản lý Edge.

XPath mẫu:

/Credential/ApiProducts/ApiProduct[Name='weather_free']/Status/text()

Hồ sơ mẫu:

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

Nhà phát triển

$ curl -H "Accept:text/xml" -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/{developer_email} \
-u email:password

Xem thêm Nhận nhà phát triển trong tài liệu tham khảo API quản lý Edge.

XPath mẫu:

/Developer/Attributes/Attribute[Name='my_custom_attribute']/Value/text()
 
/Developer/Email/text()

Hồ sơ mẫu:

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

Biến dòng

Khi hồ sơ thực thể được chỉ định trong chính sách AccessEntity được truy xuất, đối tượng hồ sơ có định dạng XML sẽ được thêm vào ngữ cảnh thông báo dưới dạng một biến. Bạn có thể truy cập vào biến này như mọi biến khác, bằng cách tham chiếu đến tên biến. Tên do người dùng cung cấp của chính sách AccessEntity được đặt làm tiền tố biến của tên biến.

Ví dụ: nếu một chính sách AccessEntity có tên là GetDeveloper được thực thi, thì hồ sơ có định dạng XML sẽ được lưu trữ trong biến có tên là AccessEntity.GetDeveloper. Sau đó, bạn có thể phân tích cú pháp hồ sơ có định dạng XML bằng XPath được xác định trong chính sách ExtractVariables, trong đó chỉ định AccessEntity.GetDeveloper làm nguồn.

Tham chiếu lỗi

Để biết thông tin liên quan, hãy xem Những điều bạn cần biết về lỗi chính sách và Xử lý lỗi.

Lỗi thời gian chạy

Không nội dung nào.

Lỗi triển khai

Tên lỗi Chuỗi lỗi Trạng thái HTTP Xảy ra khi
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] Không áp dụng Loại thực thể được sử dụng phải là một trong các loại được hỗ trợ.

Chủ đề có liên quan