Esta página foi traduzida pela API Cloud Translation.

Política AccessEntity

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Ícone da política de entidade de acesso

O quê

Obtém os perfis de entidades que especificar do arquivo de dados do Apigee. A política coloca o perfil numa variável cujo nome segue o formato AccessEntity.{policy_name}. Pode usar o AccessEntity para aceder a perfis das seguintes entidades:

App
Produto da API
Chave do consumidor
Programador

A política AccessEntity funciona como uma pesquisa de base de dados de tempo de execução baseada em políticas. Pode usar as informações do perfil devolvidas por esta política para ativar o comportamento dinâmico, como o encaminhamento condicional de pontos finais, a execução do fluxo e a aplicação de políticas.

Use a política AccessEntity para obter dados do perfil de entidade como XML (ou JSON no Apigee hybrid) e colocá-los numa variável. Identifique a entidade a obter especificando um tipo de entidade e um ou mais identificadores que especificam que entidade desse tipo quer. Posteriormente, noutra política, pode obter os dados do perfil da entidade com outra política, como uma política ExtractVariables ou AssignMessage.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Aceda a entidades AppGroups a partir de `AccessEntity`

Também pode usar AccessEntity para obter entidades AppGroup. Consulte os tipos de entidades e identificadores suportados para entidades relacionadas.

Para ver informações sobre os AppGroups e a funcionalidade suportada, consulte o artigo Usar AppGroups para organizar a propriedade de apps.

Amostras

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

Receber o email do programador para utilização noutras políticas

Configure a política AccessEntity para especificar que perfil de entidade obter do Apigee, bem como onde colocar os dados do perfil.

No exemplo seguinte, a política recebe um perfil de entidade developer, usando uma chave da API transmitida como um parâmetro de consulta para identificar o programador. O perfil é colocado numa variável cujo nome segue o formato AccessEntity.{policy_name}. Assim, 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 obter o valor do perfil da entidade do conjunto de variáveis definido por AccessEntity.

No exemplo seguinte, uma política ExtractVariables obtém um valor da variável AccessEntity.GetDeveloperProfile definida anteriormente por AccessEntity.

Tenha em atenção que o valor obtido é especificado como uma expressão XPath no elemento XMLPayload. O valor extraído é colocado numa 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 seguinte obtém o email do programador 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 do elemento

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

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

Pode aceder a várias entidades do mesmo tipo agrupando-as num 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 <AccessEntity>

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

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
`name`	O nome interno da política. O valor do atributo `name` pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento `<DisplayName>` para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
`continueOnError`	Definido como `false` para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como `true` para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
`enabled`	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
`async`	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Predefinição

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo `name` da política.
Presença	Opcional
Tipo	String

N/A

Se omitir este elemento, é usado o valor do atributo name da política.

Presença Opcional

Tipo String

Elemento <EntityIdentifier>

Especifica a entidade específica (do tipo indicado em EntityType) a obter.

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

Predefinição	N/A
Presença	Obrigatória
Tipo	String

Atributos

Atributo	Descrição	Predefinição	Presença	Tipo
ref	A variável que fornece a origem do identificador, como `request.queryparam.apikey`.	N/A	Obrigatória	String
escrever	O tipo preenchido pela variável no atributo ref, como `consumerkey`. Consulte Tipos de entidades e identificadores suportados para ver uma lista de valores.		Obrigatória	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 obter da loja de dados.

<EntityType  value="entity_type"/>

Predefinição	N/A
Presença	Obrigatória
Tipo	String

Use um elemento EntityIdentifier para especificar que entidade do tipo especificado quer. Para uma referência dos tipos de entidades, consulte o artigo Tipos de entidades e identificadores suportados.

Atributos

Atributo	Descrição	Predefinição	Presença	Tipo
valor	Um dos tipos de entidades suportados. Consulte a lista de tipos de entidades e identificadores suportados.	Nenhum	Obrigatória	String

Elemento <OutputFormat>

Nota: <OutputFormat> está disponível apenas no modo híbrido, a partir da versão híbrida 1.4.

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

<OutputFormat>XML</OutputFormat>

Predefinição	XML Se omitir este elemento, o valor predefinido é XML.
Presença	Opcional
Tipo	String (XML ou JSON)

Predefinição

XML

Se omitir este elemento, o valor predefinido é XML.

Presença

Opcional

Tipo

String (XML ou JSON)

Elemento <SecondaryIdentifier>

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

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

Predefinição	N/A
Presença	Opcional
Tipo	String

Use SecondaryIdentifier quando especificar apenas um EntityIdentifier não garante que recebe uma única entidade. Consulte o artigo Restringir os resultados com identificadores secundários para mais informações.

A utilização de vários elementos SecondaryIdentifier não é suportada.

Atributos

Atributo	Descrição	Predefinição	Presença	Tipo
ref	A variável que fornece a origem do identificador, como `request.queryparam.apikey`.	N/A	Obrigatória	String
escrever	O tipo preenchido pela variável no atributo ref, como `consumerkey`. Consulte Tipos de entidades e identificadores suportados para ver uma lista de valores.		Obrigatória	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>

Notas de utilização

Restringir os resultados com identificadores secundários

Para algumas entidades, fornecer um identificador pode não ser suficientemente específico para obter a entidade que pretende. Nesses casos, pode usar um identificador secundário para restringir os resultados.

Nota: quando existem várias correspondências para uma determinada combinação de EntityIdentifier e SecondaryIdentifier, a primeira correspondência é preenchida no fluxo. Por exemplo, considere um caso em que quer obter um perfil de produto da API usando um ID da app.

A sua primeira configuração de política, possivelmente ampla, pode ter o seguinte aspeto:

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

Uma vez que uma app pode estar associada a vários produtos API, a utilização apenas do ID da app pode não devolver o produto API pretendido (pode obter apenas o primeiro de vários produtos correspondentes).

Em alternativa, para obter um resultado mais exato, pode usar um SecondaryIdentifier. Por exemplo, pode ter variáveis appname e developerid no fluxo porque estas são preenchidas por predefinição durante uma troca de OAuth 2.0. Pode usar os valores dessas variáveis numa política AccessEntity para obter detalhes do perfil na app que está a fazer o pedido.

A configuração de políticas mais específicas pode ter o seguinte aspeto:

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

Tipos de entidades e identificadores suportados

AccessEntity suporta os seguintes tipos de entidades e identificadores.

Valor de EntityType	Tipos de EntityIdentifier	Tipos de SecondaryIdentifier
`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 XML do perfil da entidade

Para obter o valor do perfil da entidade pretendido com o XPath, tem de saber algo sobre a estrutura do XML do perfil. Para ver um exemplo da estrutura, use uma chamada da API Apigee para obter XML para a entidade pretendida. Para ver detalhes, consulte a referência da API Apigee.

As secções seguintes incluem código para chamadas API, juntamente com XML de exemplo da chamada.

Apps

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

Consulte também Get app by app ID 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"

Consulte também Get developer app details na referência da API Apigee.

Perfil de exemplo:

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

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

Consulte também Get API product na referência da API Apigee.

Exemplo de XPath que obtém o segundo recurso da API (URI) do produto da API denominado weather_free:

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

Perfil de exemplo devolvido 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 consumidor

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 Obtenha detalhes importantes de uma app de programador na referência da API Apigee.

Exemplo de XPath:

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

Perfil de exemplo:

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

Programador

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

Consulte também Get developer na referência da API Apigee.

Exemplo de XPath:

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

/Developer/Email/text()

Perfil de exemplo:

<?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 da entidade especificado na política AccessEntity é obtido, o objeto de perfil é adicionado ao contexto da mensagem como uma variável. Pode aceder a esta variável como a qualquer outra variável, com referência ao nome da variável. O nome da política AccessEntity fornecido pelo utilizador é definido como o prefixo da variável do nome da variável.

Por exemplo, se for executada uma política de AccessEntity com o nome GetDeveloper, o perfil é armazenado na variável denominada AccessEntity.GetDeveloper. Em seguida, o perfil pode ser analisado através de um XPath definido numa política ExtractVariables que especifica AccessEntity.GetDeveloper como origem.

Referência de erro

Para informações relacionadas, consulte os artigos O que precisa de saber sobre erros de políticas e Como processar falhas.

Erros de tempo de execução

Nenhum.

Erros de implementação

Nome do erro	String de falha	Estado de HTTP	Ocorre quando
`InvalidEntityType`	`Invalid type [entity_type] in ACCESSENTITYStepDefinition [policy_name]`	N/A	O tipo de entidade usado tem de ser um dos tipos suportados.

Tópicos relacionados

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

Política AccessEntity Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O quê

Aceda a entidades AppGroups a partir de AccessEntity

Amostras

Receber o email do programador para utilização noutras políticas

Referência do elemento

Atributos <AccessEntity>

Elemento <DisplayName>

Elemento <EntityIdentifier>

Atributos

Exemplo

Elemento <EntityType>

Atributos

Elemento <OutputFormat>

Elemento <SecondaryIdentifier>

Atributos

Exemplo

Notas de utilização

Restringir os resultados com identificadores secundários

Tipos de entidades e identificadores suportados

Exemplo de XML do perfil da entidade

Apps

Produto da API

Chave do consumidor

Programador

Variáveis de fluxo

Referência de erro

Erros de tempo de execução

Erros de implementação

Tópicos relacionados

Política AccessEntity

Aceda a entidades AppGroups a partir de `AccessEntity`