Política de AccessEntity

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

ícone de acesso à política da entidade

Conteúdo

Recupera os perfis de entidade especificados do armazenamento de dados da Apigee. 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
  • 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 dados de perfil da entidade como XML (ou JSON na Apigee híbrida) e colocar eles 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.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Acessar entidades AppGroups por meio de AccessEntity

Também é possível usar AccessEntity para recuperar entidades AppGroup. Consulte Tipos de entidade e identificadores compatíveis para conferir as entidades relacionadas.

Para mais informações sobre AppGroups e a funcionalidade compatível, consulte Como usar AppGroups para organizar a propriedade de aplicativo.

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 qual perfil de entidade receber da Apigee e onde colocar os dados de 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 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>

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. Consulte também:

 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.

 verdadeiro Opcional
async

Esse atributo está obsoleto.

 falso Descontinuado

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/A Obrigatório String
tipo O tipo preenchido pela variável no atributo ref. como consumerkey. Consulte Tipos e identificadores de entidade compatíveis para ver uma lista de valores. 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>

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 compatíveis para ver uma lista. Nenhum Obrigatório String

Elemento <OutputFormat>

Especifica o formato retornado pela política AccessEntity: XML ou JSON.

<OutputFormat>XML</OutputFormat>
Padrão

XML

Se você omitir esse elemento, o valor padrão será XML.
Presença Opcional
Tipo String (XML ou JSON)

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/A Obrigatório String
tipo O tipo preenchido pela variável no atributo ref. como consumerkey. Consulte Tipos e identificadores de entidade compatíveis para ver uma lista de valores. 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
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

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. Use uma chamada de API da Apigee para receber XML da entidade pretendida. Para mais detalhes, consulte a referência da Apigee.

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

Apps

curl https://apigee.googleapis.com/v1/organizations/$ORG/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Veja também Receber app por ID do app na referência da API Apigee.

Ou:

$ curl https://apigee.googleapis.com/v1/organizations/$ORG/developers/$DEVELOPER_EMAIL/apps/$APP \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Veja também Receber detalhes do app do desenvolvedor na referência da API Apigee.

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 https://apigee.googleapis.com/v1/organizations/$ORG/apiproducts/$APIPRODUCT \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consulte também Ver o produto da API na referência da API da Apigee.

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>

Chave do cliente

curl https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL/apps/$APP/keys/$KEY \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Consulte também Receber detalhes importantes de um aplicativo de desenvolvedor na referência da API Apigee.

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 https://apigee.googleapis.com/v1/organizations/$ORGdevelopers/$DEVELOPER_EMAIL \
  -X GET \
  -H "Accept:text/xml" \
  -H "Authorization: Bearer $TOKEN"

Veja também Receber desenvolvedor na referência da API Apigee.

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 é 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 pelo usuário da política AccessEntity é definido como o prefixo da variável.

Por exemplo, se uma política AccessEntity com o nome GetDeveloper for executada, o perfil vai ser armazenado na variável chamada AccessEntity.GetDeveloper. O perfil pode ser analisado usando um XPath definido em uma política ExtractVariables que especifica AccessEntity.GetDeveloper como a 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