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

O que

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	Presence
`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: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	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.	false	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

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo `name` da política.
Presence	Opcional
Tipo	String

N/A

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

Presence 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
Presence	Obrigatório
Tipo	String

Atributos

Atributo	Descrição	Padrão	Presence	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
Presence	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	Presence	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>

Observação: <OutputFormat> está disponível apenas no modo híbrido, começando na versão híbrida v1.4.

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.
Presence	Opcional
Tipo	String (XML ou JSON)

Padrão

XML

Se você omitir esse elemento, o valor padrão será XML.

Presence

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
Presence	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	Presence	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.

Observação: quando houver várias correspondências para uma determinada combinação de EntityIdentifier e SecondaryIdentifier, a primeira correspondência será preenchida no fluxo. Por exemplo, considere um caso em que você quer receber um perfil de produto de API usando um ID do app.

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

ExtractVariables: política ExtractVariables
AssignMessage: política AssignMessage

Política de AccessEntity

O que

Acessar entidades AppGroups por meio de AccessEntity

Amostras

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

Referência de elemento

Atributos de <AccessEntity>

Elemento <DisplayName>

Elemento <EntityIdentifier>

Atributos

Exemplo

Elemento <EntityType>

Atributos

Elemento <OutputFormat>

Elemento <SecondaryIdentifier>

Atributos

Exemplo

Observações sobre uso

Como restringir resultados com identificadores secundários

Identificadores e tipos de entidade compatíveis

Exemplo de perfil de entidade XML

Apps

Produto de API

Chave do cliente

Desenvolvedor

Variáveis de fluxo

Referência de erros

Erros de execução

Erros de implantação

Temas relacionados

Acessar entidades AppGroups por meio de `AccessEntity`