Usar conjuntos de propriedades

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

Veja a documentação do Apigee Edge.

Um conjunto de propriedades é uma coleção personalizada de pares de chave/valor que armazenam dados. Os proxies de API podem obter estes dados quando são executados.

Por que motivo deve usar conjuntos de propriedades?

Normalmente, usa conjuntos de propriedades para armazenar dados que não expiram e que não devem ser codificados diretamente na lógica do proxy da API. Pode aceder aos dados do conjunto de propriedades em qualquer lugar num proxy onde possa aceder a variáveis de fluxo.

Um exemplo de utilização comum para conjuntos de propriedades é fornecer valores associados a um ambiente ou outro. Por exemplo, pode criar um conjunto de propriedades com âmbito de ambiente com valores de configuração específicos dos proxies em execução no seu ambiente de teste e outro conjunto para o seu ambiente de produção.

Por 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, pode armazenar informações de planeamento de trajeto 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

Âmbitos das definições de propriedade

Pode restringir um conjunto de propriedades a uma revisão ou um ambiente de proxy de API quando cria o conjunto de propriedades. Não pode definir o âmbito de um conjunto de propriedades para uma organização.

A tabela seguinte explica o comportamento e a administração dos conjuntos de propriedades com proxy de API e âmbito da organização:

Âmbito Comportamento do tempo de execução Administração
proxy de API As propriedades só estão disponíveis para a revisão do proxy de API que contém o recurso de conjunto de propriedades. Nenhum outro proxy de API ou revisão do mesmo proxy pode aceder a esse conjunto de propriedades específico. Os administradores podem usar a API Apigee /resourcefiles ou a IU para criar e editar conjuntos de propriedades. Guardar o proxy de API na IU cria uma nova revisão, e o conjunto de propriedades modificado é associado apenas 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 noutros ambientes não podem aceder a esse conjunto de propriedades. Os administradores têm de usar a API Apigee /resourcefiles para criar, ver, atualizar ou eliminar conjuntos de propriedades com âmbito de ambiente. Estes conjuntos de propriedades não são apresentados e não podem ser editados na IU do Apigee.

Limites do conjunto de propriedades

O Apigee impõe limites aos conjuntos de propriedades, conforme descrito em Limites. Além disso, os ficheiros de conjunto de propriedades têm de usar a mesma sintaxe que os ficheiros de propriedades Java, com uma exceção: não pode usar chavetas {} em ficheiros de conjunto de propriedades.

Crie ficheiros de conjunto de propriedades

Normalmente, armazena os valores do conjunto de propriedades como pares de nome/valor num ficheiro. Os ficheiros de conjuntos de propriedades são ficheiros de recursos do tipo properties.

Os ficheiros de conjunto de propriedades suportam a mesma sintaxe que os ficheiros de propriedades Java. Por exemplo, podem conter valores Unicode e usar carateres # ou ! como marcadores de comentários. Tenha em atenção esta exceção: não pode usar chavetas {} em ficheiros de conjunto de propriedades.

Tem de adicionar o sufixo .properties ao nome de um ficheiro de propriedade. Por exemplo: myconfig.my_key.properties é permitido, mas myconfig.my_key não é permitido.

A estrutura de uma especificação do conjunto de propriedades é: property_set_name.property_name.properties O nome do conjunto de propriedades 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 são permitidos.

O exemplo que se segue mostra um ficheiro 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 ficheiro de conjunto de propriedades, carregue-o para o Apigee através da IU ou da API.

Faça a gestão dos conjuntos de propriedades através da IU

Faça a gestão de conjuntos de propriedades com âmbito numa revisão de proxy de API através da IU da mesma forma que gere outros recursos. Para mais informações, consulte o artigo Gerir recursos através da IU.

Faça a gestão de conjuntos de propriedades através da API

Faça a gestão de conjuntos de propriedades com âmbito definido para uma revisão ou um ambiente de proxy de API através da API, conforme descrito nas secções seguintes.

Crie conjuntos de propriedades através da API

As secções seguintes descrevem como criar conjuntos de propriedades com âmbito definido para uma revisão ou um ambiente de proxy de API através da API.

Crie conjuntos de propriedades com âmbito numa revisão de proxy de API através da API

Para criar um conjunto de propriedades com âmbito numa revisão do proxy de API através da API:

  1. Crie o ficheiro do conjunto de propriedades.
  2. Adicione o ficheiro de conjunto de propriedades a um pacote de configuração de proxy de API.
  3. Carregue o pacote através da API Create API proxy ou da API Update API proxy revision.

Crie conjuntos de propriedades com âmbito num ambiente através da API

Para adicionar um conjunto de propriedades com âmbito num ambiente através da API, crie o ficheiro do conjunto de propriedades e, em seguida, carregue-o para um ambiente na sua organização emitindo um pedido POST para o seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles

Inclua as seguintes informações no seu pedido:

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

O exemplo seguinte importa um conjunto de propriedades denominado MyPropSet do ficheiro /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 a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl.

Segue-se um exemplo da resposta. 

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

Para mais informações, consulte o artigo API de ficheiros de recursos de criação.

Veja conjuntos de propriedades através da API

As secções seguintes descrevem como ver conjuntos de propriedades com âmbito num ambiente através da API.

Veja todos os conjuntos de propriedades com âmbito num ambiente através da API

Para ver todos os conjuntos de propriedades com âmbito num ambiente através da API, emita um pedido GET ao seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties

O exemplo seguinte apresenta 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"

$TOKEN está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl.

Segue-se um exemplo da resposta. 

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

Para mais informações, consulte o artigo API List environment resource files.

Veja o conteúdo de um conjunto de propriedades com âmbito num ambiente através da API

Para ver o conteúdo de um conjunto de propriedades com âmbito definido para um ambiente através da API, emita um pedido GET para o seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/properties/name

O exemplo seguinte apresenta os conteúdos 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"

$TOKEN está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl.

Segue-se um exemplo da 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 o artigo API List environment resource files.

Atualize conjuntos de propriedades através da API

As secções seguintes descrevem como atualizar conjuntos de propriedades com âmbito numa revisão ou num ambiente de proxy de API através da API.

Atualize conjuntos de propriedades com âmbito numa revisão de proxy de API através da API

Para atualizar um conjunto de propriedades com âmbito numa revisão de proxy de API através da API:

  1. Atualize o ficheiro do conjunto de propriedades.
  2. Transfira o pacote de configuração do proxy da API através da API Get API proxy revision com as seguintes opções:
    • Defina o parâmetro de consulta format como bundle
    • Definir o cabeçalho Accept como application/zip
  3. Adicione o ficheiro de conjunto de propriedades ao pacote de configuração do proxy de API.
  4. Carregue o pacote de configuração do proxy de API através da API Update API proxy revision.

Atualize conjuntos de propriedades com âmbito num ambiente através da API

Para atualizar um conjunto de propriedades com âmbito num ambiente através da API, atualize o ficheiro do conjunto de propriedades e, em seguida, carregue-o para um ambiente na sua organização emitindo um pedido PUT para o seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Inclua as seguintes informações no seu pedido:

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

O exemplo seguinte atualiza o conjunto de propriedades MyPropSet com o conteúdo do ficheiro /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

$TOKEN está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl.

Segue-se um exemplo da resposta. 

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

Para mais informações, consulte o artigo API de ficheiros de recursos de atualização.

Elimine conjuntos de propriedades através da API

As secções seguintes descrevem como eliminar conjuntos de propriedades com âmbito numa revisão ou num ambiente de proxy de API através da API.

Elimine conjuntos de propriedades com âmbito numa revisão de proxy de API através da API

Para eliminar um conjunto de propriedades com âmbito numa revisão de proxy de API através da API:

  1. Transfira o pacote de configuração do proxy da API através da API Get API proxy revision com as seguintes opções:
    • Defina o parâmetro de consulta format como bundle
    • Definir o cabeçalho Accept como application/zip
  2. Elimine o ficheiro de conjunto de propriedades do pacote de configuração do proxy da API.
  3. Carregue o pacote de configuração do proxy de API através da API Update API proxy revision.

Elimine conjuntos de propriedades com âmbito num ambiente através da API

Para eliminar um conjunto de propriedades com âmbito num ambiente através da API, emita um pedido DELETE para o seguinte recurso: https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/resourcefiles/{type}/{name}

Transmita as seguintes informações com o seu pedido:

  • Defina {type} como properties
  • Defina {name} como o nome do conjunto de propriedades que quer eliminar

O exemplo seguinte elimina 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"

$TOKEN está definido como a sua chave de acesso OAuth 2.0, conforme descrito em Obter uma chave de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte a secção Usar o curl.

Segue-se um exemplo da resposta. 

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

Para mais informações, consulte o artigo API Delete resource file.

Aceda aos valores do conjunto de propriedades

Aceda aos valores definidos das propriedades em qualquer parte de um proxy de API onde pode aceder a variáveis de fluxo: em políticas, fluxos, código JavaScript, etc.

Para aceder a valores num conjunto de propriedades, use a seguinte sintaxe:

propertyset.[property_set_name].[property_name]

Onde:

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

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

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

O exemplo seguinte obtém o valor da propriedade foo no conjunto de propriedades com o nome "MyPropSet":

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

Também pode usar a política ExtractVariables para obter o valor de uma propriedade de um conjunto de propriedades e atribuí-lo a outra variável, como mostra o exemplo seguinte:

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

Atribua dinamicamente o valor de uma chave definida de propriedade através da política Assign Message

Pode usar a política Assign Message para atribuir o valor da chave do conjunto de propriedades a uma variável de fluxo dinamicamente. Para ver detalhes, consulte a descrição de PropertySetRef na referência da política de atribuição de mensagens.

Para utilizadores do Apigee Hybrid

Se estiver a usar o Apigee hybrid, tenha em atenção o seguinte:

  1. O plano de gestão híbrido valida o conjunto de propriedades. Se for válido, as propriedades são armazenadas no plano de gestão.
  2. O sincronizador obtém os dados do conjunto de propriedades e armazena-os localmente no plano de execução.
  3. O processador de mensagens carrega o conjunto de propriedades transferido e disponibiliza-o aos proxies de execução.