Como usar conjuntos de propriedades

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

Confira a documentação da Apigee Edge.

Um conjunto de propriedades é uma coleção personalizada de pares de chave-valor que armazena dados. Os proxies da API podem recuperar esses dados quando são executados.

Por que usar conjuntos de propriedades?

Normalmente, você usa conjuntos de propriedades para armazenar dados que não expiram e que não podem ser codificados na lógica de proxy da API. É possível acessar dados de conjuntos de propriedades em qualquer lugar de um proxy de que se tenha acesso às variáveis de fluxo.

Um caso de uso comum para conjuntos de propriedades é fornecer valores associados a um ambiente ou a outro. Por exemplo, é possível criar um conjunto de propriedades no escopo do ambiente com valores de configuração específicos aos proxies em execução no ambiente de teste, e o outro conjunto para o ambiente de produção.

Exemplo:

O conjunto de propriedades prod-env.properties contém a propriedade log-level=error
O conjunto de propriedades test-env.properties contém a propriedade log-level=debug

Da mesma forma, é possível armazenar informações de roteamento específicas do ambiente:

O conjunto de propriedades test-env.properties contém a propriedade db-url=mydomain.test.datasource.com.
O conjunto de propriedades prod-env.properties contém a propriedade db-url=mydomain.prod.datasource.com

Escopos do conjunto de propriedades

É possível definir o escopo de uma propriedade definida para uma revisão de proxy ou ambiente de API ao criar o conjunto de propriedades. Não é possível definir o escopo de uma propriedade definida para uma organização.

A tabela a seguir explica o comportamento e o gerenciamento de conjuntos de propriedades com proxy de API e escopo da organização:

Escopo	Comportamento do ambiente de execução	Administração
Proxy de API	As propriedades estão disponíveis apenas para a revisão do proxy de API que contém o recurso do conjunto de propriedades. Nenhum outro proxy de API ou revisão do mesmo proxy pode acessar esse conjunto de propriedades específico.	Os administradores podem usar a API Apigee /resourcefiles ou a IU para criar e editar conjuntos de propriedades. Salvar o proxy de API na IU criará uma nova revisão e o conjunto de propriedades modificado será associado somente a essa revisão.
Ambiente	As propriedades estão disponíveis para todas as revisões de todos os proxies de API nesse ambiente. Os proxies de API em outros ambientes não podem acessar esse conjunto de propriedades.	Os administradores precisam usar a API da Apigee /resourcefiles para criar, visualizar, atualizar ou excluir conjuntos de propriedades com escopo de ambiente. Esses conjuntos de propriedades não são exibidos e não podem ser editados na IU da Apigee.

Limites do conjunto de propriedades

A Apigee impõe limites aos conjuntos de propriedades, conforme descrito em Limites. Além disso, os arquivos de conjuntos de propriedades precisam usar a mesma sintaxe que os arquivos de propriedades Java, com uma exceção: não é possível usar chaves {} em arquivos de conjuntos de propriedades.

Criar arquivos de conjuntos de propriedades

Normalmente, você armazena valores de conjuntos de propriedades como pares de nome/valor em um arquivo. Os arquivos de conjuntos de propriedades são arquivos de recursos do tipo properties.

Os arquivos de conjuntos de propriedades aceitam a mesma sintaxe de arquivos de propriedades Java (em inglês). Por exemplo, eles podem conter valores Unicode e usar caracteres # ou ! como marcadores de comentário. Observe esta exceção: não é possível usar chaves {} em arquivos de conjuntos de propriedades.

É preciso adicionar o sufixo .properties a um nome de arquivo de propriedade. Por exemplo: myconfig.my_key.properties é permitido, mas myconfig.my_key não.

A estrutura de uma especificação de conjuntos de propriedades é: property_set_name.property_name.properties O nome do conjunto e o nome da propriedade não podem ter pontos. Por exemplo: myconfig.my_key.properties é permitido, mas myconfig.my.key.properties e my.config.my_key.properties não.

O exemplo a seguir mostra um arquivo de conjunto de propriedades simples que define várias propriedades:

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

Depois de criar um arquivo de conjunto de propriedades, faça o upload dele para a Apigee usando a IU ou a API.

Gerenciar conjuntos de propriedades usando a IU

Gerencie conjuntos de propriedades com escopo para uma revisão de proxy de API usando a IU da mesma maneira que você gerencia outros recursos. Para mais informações, consulte Gerenciar recursos usando a IU.

Gerenciar conjuntos de propriedades usando a API

Gerencie conjuntos de propriedades com escopo para uma revisão ou um ambiente de proxy de API usando a API, conforme descrito nas seções a seguir.

Criar conjuntos de propriedades usando a API

As seções a seguir descrevem como criar conjuntos de propriedades com escopo para uma revisão ou ambiente de proxy da API usando a API.

Criar conjuntos de propriedades com escopo para uma revisão de proxy de API usando a API

Para criar um conjunto de propriedades com escopo para uma revisão de proxy de API usando a API:

Crie o arquivo de conjunto de propriedades.
Adicione o arquivo de conjunto de propriedades a um pacote de configuração do proxy de API.
Faça upload do pacote usando a API para Criar proxy de API ou Atualizar a revisão de proxy da API.

Criar conjuntos de propriedades com escopo para um ambiente usando a API

Para adicionar um conjunto de propriedades com escopo em um ambiente usando a API, crie o arquivo do conjunto de propriedades e faça upload dele em um ambiente na organização emitindo uma solicitação POST ao seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

Inclua as seguintes informações com a solicitação:

Defina o parâmetro de consulta name como o nome do conjunto de propriedades.
Defina o parâmetro de consulta type como properties.
Transmita o conteúdo do arquivo de conjunto de propriedades como application/octet-stream ou multipart/form-data.

Observação: ao importar um arquivo de conjunto de propriedades usando a API, pode ser necessário aplicar chmod às permissões do arquivo para que a ferramenta de desenvolvimento (como curl) possa fazer upload dele.

O exemplo a seguir importa um conjunto de propriedades chamado MyPropSet do arquivo /Users/myhome/myprops.properties:

curl -X POST "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles?name=MyPropSet&type=properties"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops.properties

$TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl.

Veja a seguir um exemplo de resposta.

{
  "name": "MyPropSet",
  "type": "properties"
}

Para mais informações, consulte Criar API de arquivo de recursos.

Ver conjuntos de propriedades usando a API

Veja nas seções a seguir como visualizar conjuntos de propriedades com escopo para um ambiente usando a API.

Visualizar todos os conjuntos de propriedades com escopo para um ambiente usando a API

Para visualizar todos os conjuntos de propriedades com escopo para um ambiente usando a API, emita uma solicitação GET ao seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

No exemplo a seguir, estão listados todos os conjuntos de propriedades no ambiente de teste:

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties" \
  -H "Authorization: Bearer $TOKEN"

Veja a seguir um exemplo de resposta.

{
  "resourceFile": [
    {
      "name": "MyPropSet",
      "type": "properties"
    }
  ]
}

Para mais informações, consulte Listar APIs de arquivos de recursos de ambiente.

Visualizar o conteúdo de um conjunto de propriedades com escopo para um ambiente usando a API

Para ver o conteúdo de um conjunto de propriedades com escopo para um ambiente usando a API, emita uma solicitação GET para o seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

O exemplo a seguir exibe o conteúdo da propriedade MyPropSet definida no ambiente de teste:

curl -X GET "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet" \
  -H "Authorization: Bearer $TOKEN"

Veja a seguir um exemplo de resposta.

# myProps.properties file
# General properties
foo=bar
baz=biff

# Messages/notes/warnings
message=This is a basic message.
note_message=This is an important message.
error_message=This is an error message.

# Keys
publickey=abc123
privatekey=splitwithsoundman

Para mais informações, consulte Listar APIs de arquivos de recursos de ambiente.

Atualizar conjuntos de propriedades usando a API

As seções a seguir descrevem como atualizar conjuntos de propriedades com escopo para uma revisão ou ambiente de proxy da API usando a API.

Atualizar conjuntos de propriedades com escopo para uma revisão de proxy de API usando a API

Para atualizar um conjunto de propriedades com escopo para uma revisão de proxy de API usando a API:

Atualize o arquivo de conjunto de propriedades.
Faça o download do pacote de configuração de proxy de API usando a API para obter o proxy de API com as seguintes opções:
- Defina o parâmetro de consulta format como bundle.
- Defina o cabeçalho Accept como application/zip.
Adicione o arquivo de conjunto de propriedades ao pacote de configuração de proxy de API.
Faça o upload do pacote de configuração de proxy de API usando a API para atualizar a revisão de proxy de API.

Atualizar conjuntos de propriedades com escopo para um ambiente usando a API

Para atualizar um conjunto de propriedades com escopo para um ambiente usando a API, atualize o arquivo do conjunto de propriedades e faça upload dele para um ambiente na organização enviando uma solicitação PUT ao recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Inclua as seguintes informações com a solicitação:

Defina {type} como properties
Defina {name} como o nome do conjunto de propriedades que você quer atualizar.
Transmita o conteúdo do arquivo de conjunto de propriedades como application/octet-stream ou multipart/form-data.

O exemplo a seguir atualiza o conjunto de propriedades MyPropSet usando o conteúdo do arquivo /Users/myhome/myprops-revised.properties:

curl -X PUT "https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet"
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-type: multipart/form-data" \
  -F file=@/Users/myhome/myprops-revised.properties

Veja a seguir um exemplo de resposta.

{
  "name": "MyPropSet",
  "type": "properties"
}

Para mais informações, consulte API para atualizar arquivo de recurso.

Excluir conjuntos de propriedades usando a API

As seções a seguir descrevem como excluir conjuntos de propriedades com escopo para uma revisão ou ambiente de proxy de API usando a API.

Excluir conjuntos de propriedades com escopo para uma revisão de proxy de API usando a API

Para excluir um conjunto de propriedades com escopo para uma revisão de proxy de API usando a API:

Faça o download do pacote de configuração de proxy de API usando a API para obter o proxy de API com as seguintes opções:
- Defina o parâmetro de consulta format como bundle.
- Defina o cabeçalho Accept como application/zip.
Exclua o arquivo de conjunto de propriedades do pacote de configuração de proxy de API.
Faça o upload do pacote de configuração de proxy de API usando a API para atualizar a revisão de proxy de API.

Excluir conjuntos de propriedades com escopo para um ambiente usando a API

Para excluir um conjunto de propriedades com escopo para um ambiente usando a API, emita uma solicitação DELETE ao seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Transmita as seguintes informações com a solicitação:

Defina {type} como properties
Defina {name} como o nome do conjunto de propriedades que você quer excluir.

O exemplo a seguir exclui o conjunto de propriedades MyPropSet:

curl -X DELETE https://apigee.googleapis.com/v1/organizations/my-organization/environments/test/resourcefiles/properties/MyPropSet \
  -H "Authorization: Bearer $TOKEN"

Veja a seguir um exemplo de resposta.

{
  "name": "MyPropSet",
  "type": "properties"
}

Para mais informações, consulte Excluir API de arquivo de recursos.

Acessar valores de conjuntos de propriedades

Acesse valores de conjuntos de propriedades em qualquer lugar de um proxy de API em que seja possível acessar as variáveis de fluxo: em políticas, em fluxos, no código JavaScript e assim por diante.

Para acessar valores em um conjunto de propriedades, use a seguinte sintaxe:

propertyset.[property_set_name].[property_name]

Em que:

property_set_name é o nome do arquivo que você definiu (se usou a IU) ou o valor do parâmetro de consulta name (se você usou a API).
property_name é o nome da propriedade; Por exemplo, se o conjunto de propriedades contiver foo=bar, foo será o nome da propriedade e bar será o valor.

Por exemplo, em uma política de JavaScript, use o método getVariable() para ver um valor de um conjunto de propriedades:

context.getVariable('propertyset.property_set_name.property_name);

O exemplo a seguir obtém o valor da propriedade foo no conjunto de propriedades chamado "MyPropSet":

context.getVariable('propertyset.MyPropSet.foo);

Também é possível usar a política ExtractVariables para acessar o valor de uma propriedade de um conjunto de propriedades e atribuí-la a outra variável, como no exemplo a seguir:

<ExtractVariables name="ExtractVariables-1">
   <DisplayName>Extract a portion of the url path</DisplayName>
   <Source>request</Source>
   <Variable name="propertyset.MyPropSet.foo">
      <Pattern>{myVar}</Pattern>
   </Variable>
   <VariablePrefix>foobar</VariablePrefix>
   <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>

Neste exemplo, a política lê a variável do atributo name e atribui o valor à variável no elemento Pattern.

Atribuir o valor de uma chave de conjuntos de propriedades de maneira dinâmica usando a política "Atribuir mensagem"

É possível usar a política "Atribuir mensagem" para atribuir dinamicamente o valor da chave do conjunto de propriedades a uma variável de fluxo. Para mais detalhes, consulte a descrição de PropertySetRef na referência da política "Atribuir mensagem".

Para usuários da Apigee híbrida

Se você estiver usando a Apigee híbrida, observe o seguinte:

O plano de gerenciamento híbrido valida o conjunto de propriedades. Se forem válidas, as propriedades serão armazenadas no plano de gerenciamento.
O Synchronizer recupera os dados do conjunto de propriedades e os armazena localmente no plano do ambiente de execução.
O Message Processor carrega o conjunto de propriedades transferido por download e o disponibiliza proxies em execução.