Como configurar e implantar ambientes

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

Confira a documentação da Apigee Edge.

Um ambiente é um contexto de execução de tempo de execução para os proxies de API e os fluxos compartilhados que você quer implantar. Você precisa implantar os proxies de API e os fluxos compartilhados em um ou mais ambientes antes que eles possam ser acessados para teste. Para mais informações sobre ambientes, consulte Sobre ambientes e grupos de ambiente.

Configure e implante os ambientes conforme descrito nas seções a seguir. Consulte também Como gerenciar pastas e arquivos em um espaço de trabalho do Apigee.

Como configurar um ambiente

Antes de implantar um ambiente, você precisa configurá-lo para identificar os proxies de API e os fluxos compartilhados que quer implantar e configurar os ganchos de fluxo compartilhados ou servidores de destino, conforme necessário.

Para configurar um ambiente, crie o ambiente e edite a configuração definida na tabela a seguir.

Configuração Descrição
Depurar máscaras (debugmasks.json) Define configurações de máscara para mascarar dados específicos nas sessões de rastreamento e depuração.
Implantações (deployments.json) Defina os proxies da API e os fluxos compartilhados na implantação.
Ganchos de fluxo (flowhooks.json) Anexe fluxos compartilhados aos ganchos de fluxo para que sejam executados no mesmo local para todos os proxies de API implantados no ambiente.
Servidores de destino (targetservers.json) Separe seus endpoints concretos dos endpoints de destino para aceitar o balanceamento de carga e o failover em várias instâncias do servidor de back-end.
Keystores (keystores.json) Adicione o suporte TLS aos seus endpoints de destino e servidores de destino.

Além disso, se você usar qualquer política que exija recursos, poderá gerenciar recursos no nível do ambiente, conforme necessário.

Como criar um ambiente

Para criar um ambiente na Apigee no Cloud Code:

  1. Realize uma das seguintes ações:

    • Posicione o cursor sobre a pasta environments na seção da Apigee e clique em Ícone de criação.

      + é exibido quando você posiciona o cursor sobre a pasta de ambientes

    • Selecione View > Command Palette para abrir a paleta de comando e selecione Cloud Code: Create Apigee Environment.

    O assistente "Criar ambiente" é aberto.

  2. Digite um nome para o ambiente e pressione Enter.

O ambiente é adicionado à pasta environments na seção da Apigee, como mostrado na figura a seguir.

Ambientes com arquivos deployments.json, flowhooks.json e arquivos targetservers.json

Configure o ambiente, conforme descrito nas seções a seguir.

Como configurar máscaras de depuração (debugmask.json)

A Apigee permite definir configurações de máscara para mascarar dados específicos nas sessões de rastreamento e depuração. Quando os dados são mascarados, eles são substituídos por asteriscos na saída de trace. Exemplo:

<description>**********</description>

Para mais informações, consulte Como mascarar dados confidenciais.

Para configurar máscaras de depuração, atualize o arquivo debugmask.json editando o arquivo diretamente.

Veja a seguir um exemplo da estrutura básica de uma configuração de máscara no formato JSON. Para saber mais sobre os campos de configuração de máscara mostrados no exemplo, consulte DebugMask. 

{
  "namespaces": {
    "myco": "https://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "faultXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "requestJSONPaths": [
    "$.store.book[].author"
  ],
  "responseJSONPaths": [
    "$.store.book[].author"
  ],
  "faultJSONPaths": [
    "$.store.book[*].author"
  ],
  "variables": [
    "request.header.user-agent",
    "request.formparam.password"
  ]
}

Como configurar as implantações (deployments.json)

Configure os proxies de API e os fluxos compartilhados que você quer incluir na implantação.

Para configurar as implantações, atualize o arquivo deployments.json usando o assistente de configuração (descrito abaixo) ou editando o arquivo diretamente.

Para configurar as implantações usando o assistente de configuração:

  1. Posicione o cursor sobre o arquivo deployments.json do ambiente e clique em Ícone do assistente.

    ícone de configurações é exibido quando você posiciona o cursor sobre a pasta deployments.json

  2. Percorra o assistente de configuração para selecionar as implantações e preencher automaticamente os campos no arquivo deployments.json.
    O arquivo deployments.json será aberto no editor.

  3. Edite a configuração conforme necessário.

  4. Selecione Arquivo > Salvar ou ⌘S para salvar suas edições.

O exemplo a seguir configura a implantação para incluir o proxy de API helloworld e os fluxos compartilhados mysharedflow e hw-sharedflow:

{
  "proxies" : [
     "helloworld"
  ],
  "sharedflows" : [
     "mysharedflow",
     "hw-sharedflow"
  ]
}

Como configurar contas de serviço com implantações de proxy e fluxo compartilhado

Os proxies de API que dependem de um serviço do Google como back-end podem exigir que uma conta de serviço do Google Cloud seja associada à implantação. Consulte Como usar a autenticação do Google.

Ao editar o arquivo deployments.json, é possível associar o proxy de API ou o fluxo compartilhado a uma conta de serviço do Google Cloud. Exemplo: 

{
  "name": "proxy-name",
  "serviceAccount": "associated-service-account"
}

O exemplo a seguir mostra uma configuração de implantação em que as contas de serviço estão associadas ao proxy de API helloworld e ao fluxo compartilhado mysharedflow. No entanto, o proxy healthcheck e o fluxo compartilhado hw-sharedflow não estão associados a uma conta de serviço:

{
  "proxies": [
    {
      "name": "helloworld",
      "serviceAccount": "myserviceaccount@myorg.iam.gserviceaccount.com"
    },
    "healthcheck"
  ],
  "sharedflows": [
    {
      "name": "mysharedflow",
      "serviceAccount": "myserviceaccount@myorg.iam.gserviceaccount.com"
    },
    "hw-sharedflow"
  ]
}

Saiba como configurar o emulador da Apigee para testar recursos de autenticação de conta de serviço no proxy de API.

Como anexar fluxos compartilhados usando ganchos de fluxo (flowhooks.json)

Com um gancho de fluxo, você anexa um fluxo compartilhado para que ele seja executado no mesmo lugar para todos os proxies de API implantados em um ambiente específico. Isso gera uma sequência de lógica implementada e implantada separadamente que não faz parte do código de implementação de um proxy. Especificamente, é possível anexar um fluxo compartilhado nos seguintes locais do fluxo de proxy da API:

  • Antes de um endpoint do proxy da API ser executado (PreProxyFlowHook)
  • Depois que o endpoint do proxy da API é executado e imediatamente antes da resposta ao cliente (PostProxyFlowHook)
  • Antes de um endpoint de destino ser executado (PreTargetFlowHook)
  • Apóa a resposta de destino ser executada (PostTargetFlowHook)

Para mais informações sobre ganchos de fluxo, consulte Como anexar fluxos compartilhados usando ganchos de fluxo.

Para anexar fluxos compartilhados usando ganchos de fluxo, atualize o arquivo flowhooks.json usando o assistente de configuração (descrito abaixo) ou editando o arquivo diretamente.

Para configurar as implantações usando o assistente de configuração:

  1. Posicione o cursor sobre o arquivo flowhooks.json do ambiente e clique em Ícone do assistente.
  2. Percorra o assistente de configuração para selecionar os fluxos compartilhados a serem anexados em locais específicos no fluxo do proxy da API e campos de preenchimento automático no arquivo flowhooks.json.
    O arquivo flowhooks.json será aberto no editor.
  3. Edite a configuração conforme necessário.
  4. Selecione Arquivo > Salvar ou ⌘S para salvar suas edições.

O exemplo a seguir vincula o mysharedflow ao PreProxyFlowHook para que ele seja executado antes da execução de um endpoint de proxy da API:

{
  "PreProxyFlowHook": {
    "continueOnError": true,
    "sharedFlow": "mysharedflow",
    "description": "Shared enforced before a proxy endpoint executes."
  }
}

Como configurar os servidores de destino (targetservers.json)

Os servidores de destino (TargetServers) separam os URLs de endpoint concretos das configurações do endpoint de destino (TargetEndpoint). Em vez de definir um URL concreto na configuração, é possível configurar um ou mais TargetServers nomeados. Depois, referencie cada TargetServer pelo nome em uma TargetEndpoint HTTPConnection.

Para saber mais sobre os servidores de destino, consulte os tópicos a seguir:

Para configurar os servidores de destino, atualize o arquivo targetservers.json usando o assistente de configuração (descrito abaixo) ou editando o arquivo diretamente. Para uma descrição dos campos no arquivo targetservers.json, consulte Recurso: TargetServer.

Para configurar os servidores de destino usando o assistente de configuração:

  1. Posicione o cursor sobre o arquivo targetservers.json do ambiente e clique em Ícone do assistente.
  2. Percorra o assistente de configuração para configurar o servidor de destino e preencher automaticamente os campos no arquivo targetservers.json. O arquivo targetservers.jsonserá aberto no editor de arquivos.
  3. Edite a configuração conforme necessário.
  4. Selecione Arquivo > Salvar ou ⌘S para salvar suas edições.

O seguinte exemplo adiciona um novo servidor de destino ao ambiente:

[
  {
    "enabled": true,
    "description": "My first target server",
    "name": "mytargetserver",
    "host": "localhost",
    "port": 80
  }
]

O seguinte exemplo configura um servidor de destino com TLS mútuo usando keystores:

[
    {
        "name": "mtlsserver",
        "host": "mytargetserver.mydomain",
        "port": 443,
        "enabled": true,
        "protocol": "HTTP",
        "tlsInfo": {
            "enabled": true,
            "clientAuthEnabled": true,
            "keyStore": "mykeystore",
            "keyAlias": "mykeyandcert",
            "trustStore": "mytruststore"
        }
    }
]

Como configurar os keystores (keystores.json)

Os keystores definem os repositórios de certificados de segurança usados para a criptografia TLS em endpoints e servidores de destino.

Para mais informações sobre a configuração do TLS, consulte Opções para configurar o TLS.

Para configurar keystores:

  1. Abra o arquivo keystores.json do ambiente no editor. O arquivo tem dois elementos principais
    • stores: um mapa do nome do keystore e os aliases adicionados.
    • references: um mapa de todos os nomes de referência do keystore e o nome do keystore associado.
  2. Edite a configuração conforme necessário.
  3. Selecione Arquivo > Salvar ou ⌘S para salvar suas edições.

O seguinte exemplo mostra um mykeystore do keystore com dois aliases, mycert-alias e mykeycert-alias:

{
    "stores": {
      "mykeystore": {
        "my-cert-alias": {
          "cert": "/Users/jdoe/testkeys/cert1.pem"
        },
        "my-keycert-alias": {
          "key": "/Users/jdoe/testkeys/key1.pem",
          "cert": "/Users/jdoe/testkeys/cert1.pem"
        }
      }
    }
  }

Como implantar um ambiente

Implante os proxies de API e os fluxos compartilhados configurados para um ambiente de modo que eles possam ser acessados para testes.

Para implantar um ambiente:

  1. Na seção da Apigee, posicione o cursor sobre a pasta do ambiente que você quer implantar.
  2. Clique em Ícone de implantação.

    O ícone de implantação é exibido quando você posiciona o cursor sobre a pasta do ambiente de desenvolvimento.

  3. Se vários contêineres para o Apigee Emulator estiverem em execução, selecione o contêiner em que você quer implantar o ambiente.
  4. Selecione o pacote de teste que você quer exportar com a implantação ou selecione Implantar sem um pacote de teste.

    Solicitação para exportar o pacote de teste

    É possível exportar recursos de teste posteriormente, conforme descrito em Como exportar recursos de teste no emulador da Apigee.

O ambiente é implantado e as seguintes informações são exibidas na guia Saída:

Environment dev deployed successfully with revision 7

Os aplicativos implantados são exibidos no Emulador da Apigee, como mostrado abaixo.

Emulador da Apigee mostrando o aplicativo helloworld implantado e os recursos de teste ativos

Próximas etapas

Agora, teste a API.