Política de AccessEntity

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

O que

Recupera os perfis de entidade especificados do repositório de dados do Apigee Edge. A política coloca o perfil em uma variável cujo nome segue o formato AccessEntity.{policy_name}. É possível usar AccessEntity para acessar os perfis das seguintes entidades:

  • App
  • Produto de API
  • Empresa
  • Desenvolvedor da empresa
  • Chave do cliente
  • Desenvolvedor
.

A política AccessEntity funciona como uma pesquisa de banco de dados do ambiente de execução baseada em políticas. Use as informações do perfil retornadas por esta política para ativar o comportamento dinâmico, como roteamento de endpoint condicional, execução de fluxo e aplicação de políticas.

Use a política AccessEntity para receber os dados de perfil de entidade como XML e colocá-los em uma variável. Identifique a entidade a ser obtida especificando um tipo de entidade e um ou mais identificadores que especificam a entidade desse tipo. Posteriormente, em outra política, é possível recuperar os dados de perfil da entidade com outra política, como uma política ExtractVariables ou uma política AtribuirMessage.

Amostras

Os exemplos a seguir mostram AccessEntity usado em conjunto com as políticas ExtractVariables e AssignMessage para extrair o e-mail de um desenvolvedor e adicioná-lo ao cabeçalho HTTP.

Como receber o e-mail de desenvolvedor para uso em outras políticas

Configure a política AccessEntity para especificar de qual perfil de entidade você vai receber Edge, além de onde colocar os dados do perfil.

No exemplo a seguir, a política recebe um perfil de entidade developer, usando uma chave de API passada como um parâmetro de consulta para identificar o desenvolvedor. O perfil é colocado em uma variável com nome que segue o formato AccessEntity.{policy_name}. Portanto, a variável definida por esta política seria 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>

Use outra política para recuperar o valor do perfil da entidade da variável definida por AccessEntity.

No exemplo a seguir, uma política ExtractVariables recupera um valor da variável AccessEntity.GetDeveloperProfile definida anteriormente por AccessEntity.

Observe que o valor recuperado é especificado como uma expressão XPath no elemento XMLPayload. O valor extraído é colocado em uma variável 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>

A política AssignMessage a seguir recupera o e-mail do desenvolvedor definido pela política 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>

Referência de elemento

A estrutura básica de uma política AccessEntity é:

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

É possível acessar várias entidades do mesmo tipo agrupando-as em um elemento 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>

Atributos de <AccessEntity>

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

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo Descrição Padrão Presença
name

O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres.

Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

N/A Obrigatório
continueOnError

Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas.

Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.

falso Opcional
enabled

Defina como true para aplicar a política.

Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.

true Opcional
async

Esse atributo está obsoleto.

falso Obsoleto

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>
Padrão

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presença Opcional
Tipo String

Elemento <EntityIdentifier>

Especifica a entidade específica (do tipo fornecido em EntityType) a ser recebida.

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

Padrão

N/A

Presença

Obrigatório

Tipo

String

Atributos

Atributo Descrição Padrão Presença Tipo
ref

A variável que fornece a origem do identificador, como request.queryparam.apikey.

N/D Obrigatório. String
tipo O tipo preenchido pela variável no atributo ref. como consumerkey. Para ver uma lista de valores, consulte Tipos e identificadores de entidade. Obrigatório. String

Exemplo

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

Elemento <EntityType>

Especifica o tipo de entidade a ser recuperado do armazenamento de dados.

<EntityType  value="entity_type"/>

Padrão

N/A

Presença

Obrigatório

Tipo

String

Use um elemento EntityIdentifier para especificar qual entidade do tipo especificado você quer. Para ver uma referência de tipos de entidade, consulte Tipos de entidade e identificadores.

Atributos

Atributo Descrição Padrão Presença Tipo
valor Um dos tipos de entidade compatíveis. Consulte Tipos e identificadores de entidade para ver uma lista. Nenhum. Obrigatório. String

Elemento <SecondaryIdentifier>

Em conjunto com EntityIdentifier, especifica um valor para identificar a instância pretendida do EntityType fornecido.

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

Padrão

N/A

Presença

Opcional

Tipo

String

O uso de SecondaryIdentifier ao especificar apenas um EntityIdentifier não garantirá que você receba uma única entidade. Para mais informações, consulte Como restringir resultados com identificadores secundários.

Não é possível usar vários elementos SecondaryIdentifier.

Atributos

Atributo Descrição Padrão Presença Tipo
ref

A variável que fornece a origem do identificador, como request.queryparam.apikey.

N/D Obrigatório. String
tipo O tipo preenchido pela variável no atributo ref. como consumerkey. Para ver uma lista de valores, consulte Tipos e identificadores de entidade. Obrigatório. String

Exemplo

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

Observações sobre uso

Como restringir resultados com identificadores secundários

Para algumas entidades, fornecer um identificador pode não ser específico o suficiente para conseguir a entidade pretendida. Nesses casos, é possível usar um identificador secundário para restringir os resultados.

Sua primeira configuração de política pode ser semelhante a esta:

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

Como um app pode ser associado a vários produtos da API, o uso do ID do app pode não retornar o produto de API pretendido (é possível receber apenas o primeiro dos vários produtos correspondentes).

Em vez disso, para receber um resultado mais exato, use um SecondaryIdentifier. Por exemplo, é possível ter variáveis appname e developerid no fluxo porque elas são preenchidas por padrão durante uma troca do OAuth 2.0. Use os valores dessas variáveis em uma política AccessEntity para ver detalhes do perfil no aplicativo solicitante.

A configuração da política mais específica pode ser assim:

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

Identificadores e tipos de entidade compatíveis

AccessEntity aceita os tipos de entidade e identificadores a seguir.

Valor de EntityType Tipos de EntityIdentifier Tipos de SecondIdentifier
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

Exemplo de perfil de entidade XML

Para recuperar o valor do perfil de entidade pretendido com XPath, você precisa saber algo sobre a estrutura do XML do perfil. Para um exemplo da estrutura, use uma chamada de API de gerenciamento para obter XML da entidade desejada. Para mais detalhes, consulte a API de gerenciamento como referência.

As seções a seguir incluem o código das chamadas de API com o exemplo de XML da chamada.

Apps

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

Consulte também Instalar o app em um Organização por ID do app na referência da API Edge Management.

ou:

$ 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

Consulte também Adquirir Detalhes do app do desenvolvedor na referência da API Edge Management.

Exemplo de perfil:

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

Produto de API

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

Consulte também Get API Product na referência da API Edge Management.

O XPath de amostra recupera o segundo recurso de API (URI) do produto de API chamado weather_free:

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

Exemplo de perfil retornado como 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>

Empresa

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

Consulte também Adquirir Detalhes da empresa na referência da API Edge Management.

Exemplo de perfil:

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

Desenvolvedor da empresa

$ 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

Exemplo de perfil:

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

Chave do cliente

$ 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

Consulte também Acessar detalhes da chave de um app do desenvolvedor na referência da API Edge Management.

Exemplo de XPath:

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

Exemplo de perfil:

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

Desenvolvedor

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

Consulte também Conheça os desenvolvedores no referência da API Edge Management.

Exemplo de XPath:

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

Exemplo de perfil:

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

Variáveis de fluxo

Quando o perfil de entidade especificado na política AccessEntity é recuperado, o objeto de perfil formatado em XML é adicionado ao contexto da mensagem como uma variável. Ele pode ser acessado como qualquer outra variável, com referência ao nome da variável. O nome fornecido pela política da AccessEntity é definido como o prefixo da variável do nome da variável.

Por exemplo, se uma política AccessEntity com o nome GetDeveloper for executada, o perfil formatado em XML será armazenado na variável AccessEntity.GetDeveloper. O perfil em formato XML pode ser analisado usando um XPath definido em uma política ExtractVariables que especifica AccessEntity.GetDeveloper como origem.

Referência de erros

Para informações relacionadas, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Nenhum.

Erros de implantação

Nome do erro String de falha Status HTTP Ocorre quando
InvalidEntityType Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name] N/A O tipo de entidade usado precisa ser um dos tipos compatíveis.

Temas relacionados