O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Referência de operações e configurações do Edge Microgateway

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Edge Microgateway v. 3.2.x

Neste tópico, discutimos como gerenciar e configurar o Edge Microgateway.

Como fazer upgrade do Edge Microgateway se você tiver uma conexão de Internet

Nesta seção, explicamos como fazer upgrade de uma instalação do Edge Microgateway. Se você estiver operando sem uma conexão de Internet, consulte Posso instalar o Edge Microgateway sem uma conexão de Internet?.

A Apigee recomenda que você teste sua configuração atual com a nova versão antes de fazer upgrade do ambiente de produção.

Execute o seguinte comando npm para fazer upgrade para a versão mais recente do Edge Microgateway:
```
npm upgrade edgemicro -g
```
Para instalar uma versão específica do Edge Microgateway, especifique o número da versão no comando de instalação. Por exemplo, para instalar a versão 3.2.3, use o seguinte comando:
```
npm install edgemicro@3.2.3 -g
```

Confira o número da versão. Por exemplo, se você instalou a versão 3.2.3:

edgemicro --version
current nodejs version is v12.5.0
current edgemicro version is 3.2.3

Por fim, faça upgrade para a versão mais recente do proxy edgemicro-auth:
```
edgemicro upgradeauth -o $ORG -e $ENV -u $USERNAME
```

Como fazer mudanças na configuração

Os arquivos de configuração que você precisa conhecer incluem:

Arquivo de configuração padrão do sistema
Arquivo de configuração padrão para uma instância do Edge Microgateway recém-inicializada
Arquivo de configuração dinâmica para instâncias em execução

Nesta seção, discutimos esses arquivos e o que você precisa saber sobre como alterá-los.

Arquivo de configuração padrão do sistema

Quando você instala o Edge Microgateway, um arquivo de configuração padrão do sistema é colocado aqui:

prefix/lib/node_modules/edgemicro/config/default.yaml

Em que prefix é o diretório de prefixo npm. Consulte Onde o Edge Microgateway está instalado se você não conseguir localizar esse diretório.

Se você alterar o arquivo de configuração do sistema, será necessário reinicializar, reconfigurar e reiniciar o Edge Microgateway:

edgemicro init
edgemicro configure [params]
edgemicro start [params]

Arquivo de configuração padrão para instâncias do Edge Microgateway recém-inicializadas

Quando você executa edgemicro init, o arquivo de configuração do sistema (descrito acima), default.yaml, é colocado no diretório ~/.edgemicro.

Se você alterar o arquivo de configuração em ~/.edgemicro, será necessário reconfigurar e reiniciar o Edge Microgateway:

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

Arquivo de configuração dinâmica para instâncias em execução

Quando você executa edgemicro configure [params], um arquivo de configuração dinâmico é criado em ~/.edgemicro. O arquivo é nomeado de acordo com este padrão: org-env-config.yaml, em que org e env são os nomes da organização e do ambiente da Apigee Edge. Use esse arquivo para fazer mudanças na configuração e recarregá-las sem inatividade. Por exemplo, se você adicionar e configurar um plug-in, poderá recarregar a configuração sem gerar inatividade, conforme explicado abaixo.

Se o Edge Microgateway estiver em execução (opção de inatividade zero):

Atualize a configuração do Edge Microgateway:
```
edgemicro reload -o $ORG -e $ENV -k $KEY -s $SECRET
```
Em que:
- $ORG é o nome da sua organização do Edge (você precisa ser um administrador da organização).
- $ENV é um ambiente na sua organização (como "test" ou "prod").
- $KEY é a chave retornada anteriormente pelo comando de configuração.
- $SECRET é a chave retornada anteriormente pelo comando de configuração.
Por exemplo:
```
edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
  -s 05c14356e42ed1...4e34ab0cc824
```

Se o Edge Microgateway for interrompido:

Reinicie o Edge Microgateway:
```
edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
```
Em que:
- $ORG é o nome da sua organização do Edge (você precisa ser um administrador da organização).
- $ENV é um ambiente na sua organização (como "test" ou "prod").
- $KEY é a chave retornada anteriormente pelo comando de configuração.
- $SECRET é a chave retornada anteriormente pelo comando de configuração.
Exemplo:
```
edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
  -s 05c1435...e34ab0cc824
```

Veja um exemplo de arquivo de configuração. Para detalhes sobre as definições do arquivo de configuração, consulte Referência de configuração do Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Como definir variáveis de ambiente

Os comandos da interface de linha de comando que exigem valores para sua organização e ambiente do Edge, além da chave e do secret necessários para iniciar o Edge Microgateway, podem ser armazenados nestas variáveis de ambiente:

EDGEMICRO_ORG
EDGEMICRO_ENV
EDGEMICRO_KEY
EDGEMICRO_SECRET

A definição dessas variáveis é opcional. Se você as definir, não será necessário especificar os valores delas ao usar a interface de linha de comando (CLI) para configurar e iniciar o Edge Microgateway.

Como configurar o SSL no servidor do Edge Microgateway

Assista aos vídeos a seguir para saber como configurar o TLS no Apigee Edge Microgateway:

Vídeo	Descrição
Configurar o TLS de entrada unidirecional	Saiba como configurar o TLS no Apigee Edge Microgateway. Este vídeo apresenta uma visão geral do TLS e sua importância, apresenta o TLS no Edge Microgateway e demonstra como configurar o TLS unidirecional de entrada.
Configurar o TLS de entrada bidirecional	Este é o segundo vídeo sobre como configurar o TLS no Apigee Edge Microgateway. Este vídeo explica como configurar o TLS bidirecional de northbound.
Configurar TLS de sentido sul unidirecional e bidirecional	Este terceiro vídeo sobre como configurar o TLS no Apigee Edge Microgateway explica como configurar o TLS unidirecional e bidirecional sul.

É possível configurar o servidor do Microgateway para usar SSL. Por exemplo, com o SSL configurado, é possível chamar APIs pelo Edge Microgateway com o protocolo "https", desta forma:

https://localhost:8000/myapi

Para configurar o SSL no servidor do Microgateway, siga estas etapas:

Gere ou consiga um certificado SSL e uma chave usando o utilitário openssl ou o método que preferir.
Adicione o atributo edgemicro:ssl ao arquivo de configuração do Edge Microgateway. Para uma lista completa de opções, consulte a tabela abaixo. Por exemplo:
```
edgemicro:
  ssl:
   key: <absolute path to the SSL key file>
   cert: <absolute path to the SSL cert file>
   passphrase: admin123 #option added in v2.2.2
   rejectUnauthorized: true #option added in v2.2.2
   requestCert: true
```
A chave especificada no arquivo de chave SSL referenciado não pode ser criptografada.
Reinicie o Edge Microgateway. Siga as etapas descritas em Como fazer alterações na configuração, dependendo de qual arquivo de configuração você editou: o arquivo padrão ou o arquivo de configuração do ambiente de execução.

Veja um exemplo da seção edgemicro do arquivo de configuração, com o SSL configurado:

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Confira uma lista de todas as opções de servidor compatíveis:

Opção	Descrição
`key`	Caminho para um arquivo `ca.key` (no formato PEM).
`cert`	Caminho para um arquivo `ca.cert` (no formato PEM).
`pfx`	Caminho para um arquivo `pfx` que contém a chave privada, o certificado e os certificados de CA do cliente no formato PFX.
`passphrase`	Uma string que contém a senha longa da chave privada ou do PFX.
`ca`	Caminho para um arquivo que contém uma lista de certificados confiáveis no formato PEM.
`ciphers`	Uma string que descreve as criptografias a serem usadas, separadas por ":".
`rejectUnauthorized`	Se for verdadeiro, o certificado do servidor será verificado em relação à lista de CAs fornecidas. Se a verificação falhar, um erro será retornado.
`secureProtocol`	O método SSL a ser usado. Por exemplo, SSLv3_method para forçar o SSL para a versão 3.
`servername`	O nome do servidor para a extensão TLS de indicação de nome do servidor (SNI, na sigla em inglês).
`requestCert`	true para SSL bidirecional; false para SSL unidirecional

Como usar as opções de SSL/TLS do cliente

É possível configurar o Edge Microgateway para ser um cliente TLS ou SSL ao se conectar a endpoints de destino. No arquivo de configuração do Microgateway, use o elemento targets para definir as opções de SSL/TLS. É possível especificar vários destinos específicos. Confira abaixo um exemplo de vários destinos.

Este exemplo fornece configurações que serão aplicadas a todos os hosts:

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

Neste exemplo, as configurações são aplicadas apenas ao host especificado:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Veja um exemplo de TLS:

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Se você quiser aplicar as configurações de TLS/SSL a vários destinos específicos, especifique o primeiro host na configuração como "vazio", o que permite solicitações universais, e, em seguida, especifique hosts específicos em qualquer ordem. Neste exemplo, as configurações são aplicadas a vários hosts específicos:

targets:
 - host:   ## Note that this value must be "empty"
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       passphrase: admin123
       rejectUnauthorized: true
 - host: 'myserver1.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true
 - host: 'myserver2.example.com'
   ssl:
     client:
       key: /Users/myname/twowayssl/ssl/client.key
       cert: /Users/myname/twowayssl/ssl/ca.crt
       rejectUnauthorized: true

Confira uma lista de todas as opções de cliente compatíveis:

Opção	Descrição
`pfx`	Caminho para um arquivo `pfx` que contém a chave privada, o certificado e os certificados de CA do cliente no formato PFX.
`key`	Caminho para um arquivo `ca.key` (no formato PEM).
`passphrase`	Uma string que contém a senha longa da chave privada ou do PFX.
`cert`	Caminho para um arquivo `ca.cert` (no formato PEM).
`ca`	Caminho para um arquivo que contém uma lista de certificados confiáveis no formato PEM.
`ciphers`	Uma string que descreve as criptografias a serem usadas, separadas por ":".
`rejectUnauthorized`	Se for verdadeiro, o certificado do servidor será verificado em relação à lista de CAs fornecidas. Se a verificação falhar, um erro será retornado.
`secureProtocol`	O método SSL a ser usado. Por exemplo, SSLv3_method para forçar o SSL para a versão 3.
`servername`	O nome do servidor para a extensão TLS de indicação de nome do servidor (SNI, na sigla em inglês).

Como personalizar o proxy edgemicro-auth

Por padrão, o Edge Microgateway usa um proxy implantado no Apigee Edge para autenticação OAuth2. Esse proxy é implantado quando você executa edgemicro configure pela primeira vez. É possível alterar a configuração padrão desse proxy para adicionar suporte a declarações personalizadas a um JSON Web Token (JWT), configurar a expiração do token e gerar tokens de atualização. Para mais detalhes, consulte a página edgemicro-auth no GitHub.

Como usar um serviço de autenticação personalizado

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Se você quiser usar seu próprio serviço personalizado para lidar com a autenticação, mude o valor de authUri no arquivo de configuração para que ele aponte para seu serviço. Por exemplo, você pode ter um serviço que usa LDAP para verificar a identidade.

Importante: se você substituir o proxy de autenticação padrão, o novo proxy ou serviço precisará retornar um formato de resposta idêntico ao do proxy edgemicro-auth padrão.

Como gerenciar arquivos de registro

O Edge Microgateway registra informações sobre cada solicitação e resposta. Os arquivos de registro fornecem informações úteis para depuração e solução de problemas.

Onde os arquivos de registro são armazenados

Por padrão, os arquivos de registro são armazenados em /var/tmp.

Como alterar o diretório padrão do arquivo de registro

O diretório em que os arquivos de registro são armazenados é especificado no arquivo de configuração do Edge Microgateway. Consulte também Como fazer alterações na configuração.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Mude o valor de dir para especificar um diretório de arquivo de registro diferente.

Enviar registros para o console

É possível configurar a geração de registros para que as informações sejam enviadas para a saída padrão em vez de um arquivo de registro. Defina a flag to_console como verdadeira da seguinte maneira:

edgemicro:
  logging:
    to_console: true

Com essa configuração, os registros serão enviados para a saída padrão. No momento, não é possível enviar registros para stdout e para um arquivo de registro.

Como definir o nível de geração de registros

Especifique o nível de registro a ser usado na configuração edgemicro. Para uma lista completa de níveis de registro e as descrições deles, consulte Atributos do edgemicro.

Por exemplo, a configuração a seguir define o nível de registro como debug:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: debug
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Como mudar os intervalos de registro

É possível configurar esses intervalos no arquivo de configuração do Edge Microgateway. Consulte também Como fazer alterações na configuração.

Os atributos configuráveis são:

stats_log_interval: (padrão: 60) intervalo, em segundos, em que o registro de estatísticas é gravado no arquivo de registro da API.
rotate_interval: (padrão: 24) intervalo, em horas, em que os arquivos de registro são alternados. Exemplo:

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Como flexibilizar as permissões rígidas de arquivos de registro

Por padrão, o Edge Microgateway gera o arquivo de registro do aplicativo (api-log.log) com o nível de permissões do arquivo definido como 0600. Esse nível de permissão não permite que aplicativos ou usuários externos leiam o arquivo de registro. Para flexibilizar esse nível de permissão estrito, defina logging:disableStrictLogFile como true. Quando esse atributo é true, o arquivo de registro é criado com a permissão de arquivo definida como 0755. Se false ou se o atributo não for fornecido, a permissão padrão será 0600.

Adicionado na v3.2.3.

Exemplo:

edgemicro:
 logging:
   disableStrictLogFile: true

Práticas recomendadas de manutenção de arquivos de registro

Como os dados do arquivo de registro se acumulam ao longo do tempo, a Apigee recomenda que você adote as seguintes práticas:

Como os arquivos de registro podem ficar muito grandes, verifique se o diretório de arquivos de registro tem espaço suficiente. Consulte as seções a seguir: Onde os arquivos de registro são armazenados e Como alterar o diretório padrão de arquivos de registro.
Exclua ou mova os arquivos de registro para um diretório de arquivo separado pelo menos uma vez por semana.
Se a política for excluir registros, use o comando da CLI edgemicro log -c para remover (limpar) os registros mais antigos.

Convenção de nomenclatura de arquivos de registro

Cada instância do Edge Microgateway produz um arquivo de registro com uma extensão .log. A convenção de nomenclatura para arquivos de registro é a seguinte:

edgemicro-HOST_NAME-INSTANCE_ID-api.log

Exemplo:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log

Sobre o conteúdo do arquivo de registro

Adicionado na versão 2.3.3

Por padrão, o serviço de geração de registros omite o JSON de proxies, produtos e JSON Web Token (JWT) baixados. Se você quiser enviar esses objetos para o console, defina a flag de linha de comando DEBUG=* ao iniciar o Edge Microgateway. Exemplo:

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

No Windows, use SET DEBUG=*

Conteúdo do arquivo de registro "api"

O arquivo de registro "api" contém informações detalhadas sobre o fluxo de solicitações e respostas pelo Edge Microgateway. Os arquivos de registro "api" são nomeados assim:

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Para cada solicitação feita ao Edge Microgateway, quatro eventos são capturados no arquivo de registro "api":

Solicitação recebida do cliente
Solicitação de saída feita ao destino
Resposta recebida do destino
Resposta de saída para o cliente

Cada uma dessas entradas separadas é representada em uma notação abreviada para ajudar a tornar os arquivos de registro mais compactos. Confira quatro exemplos de entradas que representam cada um dos quatro eventos. No arquivo de registro, eles têm esta aparência (os números de linha são apenas para referência no documento, eles não aparecem no arquivo de registro).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Vamos analisar cada um deles:

1. Exemplo de solicitação recebida do cliente:

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

1436403888651: carimbo de data Unix
info: o nível de registro. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como alterar os intervalos de registro de alterações.
req: identifica o evento. Nesse caso, solicite ao cliente.
m: o verbo HTTP usado na solicitação.
u: a parte do URL que segue o caminho de base.
h: o host e o número da porta em que o Edge Microgateway está detectando.
r: o host e a porta remotos de onde a solicitação do cliente se originou.
i: o ID da solicitação. As quatro entradas de evento vão compartilhar esse ID. Cada solicitação recebe um ID exclusivo. Correlacionar registros de registro por ID de solicitação pode fornecer insights valiosos sobre a latência do destino.
d: a duração em milissegundos desde que a solicitação foi recebida pelo Edge Microgateway. No exemplo acima, a resposta do destino para a solicitação 0 foi recebida após 7 milissegundos (linha 3), e a resposta foi enviada ao cliente após mais 4 milissegundos (linha 4). Em outras palavras, a latência total da solicitação foi de 11 milissegundos, dos quais 7 milissegundos foram usados pelo destino e 4 milissegundos pelo próprio Edge Microgateway.

2. Exemplo de solicitação de saída feita ao destino:

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

1436403888651: carimbo de data Unix
info: o nível de registro. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como alterar os intervalos de registro de alterações.
treq: identifica o evento. Nesse caso, target.request.
m: o verbo HTTP usado na solicitação de destino.
u: a parte do URL que segue o caminho de base.
h: o host e o número da porta do destino de back-end.
i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

3. Exemplo de resposta recebida do destino

1436403888672 info tres s=200, d=7, i=0

1436403888651: carimbo de data Unix

info: o nível de registro. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como alterar os intervalos de registro de alterações.
tres: identifica o evento. Neste caso, resposta de destino.
s: o status da resposta HTTP.
d: a duração em milissegundos. O tempo que o destino levou para fazer a chamada de API.
i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

4. Exemplo de resposta enviada ao cliente

1436403888676 info res s=200, d=11, i=0

1436403888651: carimbo de data Unix

info: o nível de registro. Esse valor depende do contexto da transação e do nível de geração de registros definido na configuração edgemicro. Consulte Como definir o nível de geração de registros. Para registros de estatísticas, o nível é definido como stats. Os registros de estatísticas são informados em um intervalo regular definido com a configuração stats_log_interval. Consulte também Como alterar os intervalos de registro de alterações.
res: identifica o evento. Nesse caso, responda ao cliente.
s: o status da resposta HTTP.
d: a duração em milissegundos. Esse é o tempo total gasto pela chamada de API, incluindo o tempo gasto pela API de destino e o tempo gasto pelo próprio Edge Microgateway.
i: o ID da entrada de registro. Todas as quatro entradas de evento vão compartilhar esse ID.

Programação do arquivo de registros

Os arquivos de registro são alternados no intervalo especificado pelo atributo de configuração rotate_interval. As entradas continuarão sendo adicionadas ao mesmo arquivo de registro até que o intervalo de rotação expire. No entanto, cada vez que o Edge Microgateway é reiniciado, ele recebe um novo UID e cria um novo conjunto de arquivos de registro com esse UID. Consulte também Práticas recomendadas de manutenção de arquivos de registro.

Mensagens de erro

Algumas entradas de registro vão conter mensagens de erro. Para ajudar a identificar onde e por que os erros ocorrem, consulte a referência de erros do Edge Microgateway.

Referência de configuração do Edge Microgateway

Local do arquivo de configuração

Os atributos de configuração descritos nesta seção estão localizados no arquivo de configuração do Edge Microgateway. Consulte também Como fazer alterações na configuração.

Atributos de edge_config

Essas configurações são usadas para configurar a interação entre a instância do Edge Microgateway e o Apigee Edge.

bootstrap: (padrão: nenhum) um URL que aponta para um serviço específico do Edge Microgateway em execução na Apigee Edge. O Edge Microgateway usa esse serviço para se comunicar com o Apigee Edge. Esse URL é retornado quando você executa o comando para gerar o par de chaves pública/privada: edgemicro genkeys. Consulte Como configurar o Edge Microgateway para mais detalhes.
jwt_public_key: (padrão: nenhum) um URL que aponta para o proxy do Edge Microgateway implantado na Apigee Edge. Esse proxy serve como um endpoint de autenticação para emitir tokens de acesso assinados para clientes. Esse URL é retornado quando você executa o comando para implantar o proxy: edgemicro configure. Consulte Como configurar o Edge Microgateway para mais detalhes.
quotaUri: defina essa propriedade de configuração se quiser gerenciar cotas pelo proxy edgemicro-auth implantado na sua organização. Se essa propriedade não for definida, o endpoint de cota será padronizado para o endpoint interno do Edge Microgateway.
```
edge_config:
  quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
```

atributos do edgemicro

Essas configurações definem o processo do Edge Microgateway.

port: (padrão: 8000) o número da porta em que o processo do Edge Microgateway detecta.
max_connections: (padrão: -1) especifica o número máximo de conexões de entrada simultâneas que o Edge Microgateway pode receber. Se esse número for excedido, o seguinte status será retornado:

res.statusCode = 429; // Too many requests
max_connections_hard: (padrão: -1) o número máximo de solicitações simultâneas que o Edge Microgateway pode receber antes de encerrar a conexão. Essa configuração tem como objetivo impedir ataques de negação de serviço. Normalmente, defina-o como um número maior que max_connections.
logging:
- level: (padrão: error)
  - info: (recomendado) registra todas as solicitações e respostas que fluem por uma instância do Edge Microgateway.
  - warn: registra apenas mensagens de aviso.
  - error: registra apenas mensagens de erro.
  - debug: registra mensagens de depuração, além de mensagens de informação, aviso e erro.
  - trace: registra informações de trace para erros, além de mensagens de informação, aviso e erro.
  - none: não cria um arquivo de registro.
- dir: (padrão: /var/tmp) o diretório em que os arquivos de registro são armazenados.
- stats_log_interval: (padrão: 60) intervalo, em segundos, em que o registro de estatísticas é gravado no arquivo de registro da API.
- rotate_interval: (padrão: 24) intervalo, em horas, em que os arquivos de registro são alternados.

plugins: os plug-ins adicionam funcionalidade ao Edge Microgateway. Para saber mais sobre o desenvolvimento de plug-ins, consulte Desenvolver plug-ins personalizados.

dir: um caminho relativo do diretório ./gateway para o diretório ./plugins ou um caminho absoluto.
sequence: uma lista de módulos de plug-in para adicionar à instância do Edge Microgateway. Os módulos serão executados na ordem em que são especificados aqui.

debug: adiciona a depuração remota ao processo do Edge Microgateway.
- port: o número da porta a ser detectada. Por exemplo, configure o depurador do ambiente de desenvolvimento integrado para detectar essa porta.
- args: argumentos para o processo de depuração. Por exemplo: args --nolazy
config_change_poll_interval: (padrão: 600 segundos) o Edge Microgateway carrega uma nova configuração periodicamente e executa uma atualização se algo mudar. A sondagem detecta todas as alterações feitas no Edge (alterações em produtos, proxies compatíveis com o Microgateway etc.), bem como as alterações feitas no arquivo de configuração local.
disable_config_poll_interval: (padrão: false) defina como true para desativar a sondagem de mudanças automáticas.
request_timeout: define um tempo limite para solicitações de destino. O tempo limite é definido em segundos. Se ocorrer um tempo limite, o Edge Microgateway responderá com um código de status 504. (Adicionado na v2.4.x)
keep_alive_timeout: essa propriedade permite definir o tempo limite do Edge Microgateway (em milissegundos). (Padrão: 5 segundos) (Adicionado na v3.0.6)
headers_timeout: esse atributo limita o tempo (em milissegundos) que o analisador HTTP vai esperar para receber os cabeçalhos HTTP completos.
Exemplo:
```
edgemicro:
  keep_alive_timeout: 6000
  headers_timeout: 12000
```
Internamente, o parâmetro define o atributo Server.headersTimeout do Node.js nas solicitações. (Padrão: 5 segundos a mais do que o tempo definido com edgemicro.keep_alive_timeout. Essa configuração padrão impede que balanceadores de carga ou proxies encerrem a conexão por engano. (Adicionado na v3.1.1)
noRuleMatchAction: (string) a ação a ser realizada (permitir ou negar acesso) se a regra de correspondência especificada no plug-in accesscontrol não for resolvida (não houver correspondência). Valores válidos: ALLOW ou DENY Padrão: ALLOW (adicionado: v3.1.7)
enableAnalytics: (padrão: true) defina o atributo como false para impedir que o plug-in de análise seja carregado. Nesse caso, nenhuma chamada para a análise da Apigee Edge será feita. Se definido como true ou quando esse atributo não for fornecido, o plug-in do Analytics vai funcionar normalmente. Consulte atributos do edgemicro para mais detalhes. Adicionado na v3.1.8.
Exemplo:
```
edgemicro
  enableAnalytics=false|true
```
Se enableAnalytics estiver definido como false, mas o Edge Microgateway for iniciado usando o plug-in de métricas, o plug-in de análise funcionará normalmente, porque o plug-in de métricas precisa do plug-in de análise para funcionar. Para informações sobre o plug-in de métricas, consulte as notas da versão do Edge Microgateway v1.3.6.

on_target_response_abort: esse atributo permite controlar como o Edge Microgateway se comporta se a conexão entre o cliente (Edge Microgateway) e o servidor de destino for fechada prematuramente.

Valor	Descrição
Padrão	Se `on_target_response_abort` não for especificado, o comportamento padrão será truncar a resposta sem mostrar um erro. Nos arquivos de registro, uma mensagem de aviso é mostrada com `targetResponse aborted` e um código de resposta 502.
`appendErrorToClientResponseBody`	O erro personalizado `TargetResponseAborted` é retornado ao cliente. Nos arquivos de registro, uma mensagem de aviso é mostrada com `targetResponse aborted` e um código de resposta 502. Além disso, o erro `TargetResponseAborted` é registrado com a mensagem `Target response ended prematurely.`.
`abortClientRequest`	O Edge Microgateway cancela a solicitação e um aviso é gravado nos arquivos de registro: `TargetResponseAborted` com o código de status de solicitação 502.

Exemplo:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

atributos headers

Essas configurações definem como determinados cabeçalhos HTTP são tratados.

x-forwarded-for: (padrão: true) defina como false para impedir que os cabeçalhos x-forwarded-for sejam transmitidos ao destino. Se um cabeçalho x-forwarded-for estiver na solicitação, o valor dele será definido como o valor de client-ip no Edge Analytics.
x-forwarded-host: (padrão: true) defina como false para impedir que os cabeçalhos x-forwarded-host sejam transmitidos ao destino.
x-request-id: (padrão: verdadeiro) defina como falso para impedir que os cabeçalhos x-request-id sejam transmitidos ao destino.
x-response-time: (padrão: true) defina como false para impedir que os cabeçalhos x-response-time sejam transmitidos ao destino.
via: (padrão: true) defina como false para impedir que os cabeçalhos via sejam transmitidos ao destino.

atributos oauth

Essas configurações definem como a autenticação do cliente é aplicada pelo Edge Microgateway.

allowNoAuthorization: (padrão: false) se definido como true, as chamadas de API podem passar pelo Edge Microgateway sem nenhum cabeçalho de autorização. Defina como false para exigir um cabeçalho de autorização (padrão).
allowInvalidAuthorization: (padrão: false) se definido como true, as chamadas de API poderão ser transmitidas se o token transmitido no cabeçalho de autorização for inválido ou estiver expirado. Defina como false para exigir tokens válidos (padrão).
authorization-header: (padrão: Authorization: Bearer) o cabeçalho usado para enviar o token de acesso ao Edge Microgateway. Talvez você queira alterar o padrão nos casos em que o destino precisa usar o cabeçalho de autorização para outra finalidade.
api-key-header: (padrão: x-api-key) o nome do cabeçalho ou parâmetro de consulta usado para transmitir uma chave de API ao Edge Microgateway. Consulte também Como usar uma chave de API.
keep-authorization-header: (padrão: false) se definido como true, o cabeçalho de autorização enviado na solicitação será transmitido ao destino (ele será preservado).
allowOAuthOnly: se definido como verdadeiro, cada API precisa ter um cabeçalho de autorização com um token de acesso do portador. Permite que você use apenas o modelo de segurança do OAuth (mantendo a compatibilidade com versões anteriores). (Adicionado na versão 2.4.x)
allowAPIKeyOnly: se definido como verdadeiro, cada API precisa ter um cabeçalho x-api-key (ou um local personalizado) com uma chave de API.Permite apenas o modelo de segurança da chave de API (mantendo a compatibilidade com versões anteriores). (Adicionado na versão 2.4.x)
Não defina allowOAuthOnly e allowAPIKeyOnly como true. A configuração padrão é que as duas flags sejam definidas como falsas (para compatibilidade com versões anteriores).
gracePeriod: esse parâmetro ajuda a evitar erros causados por pequenas discrepâncias entre o relógio do sistema e os horários Not Before (nbf) ou Issued At (iat) especificados no token de autorização do JWT. Defina esse parâmetro como o número de segundos para permitir essas discrepâncias. (Adicionado na versão 2.5.7)

Atributos específicos do plug-in

Consulte "Como usar plug-ins" para saber mais sobre os atributos configuráveis de cada plug-in.

Como filtrar proxies

É possível filtrar quais proxies compatíveis com o Microgateway uma instância do Edge Microgateway vai processar. Quando o Edge Microgateway é iniciado, ele faz o download de todos os proxies compatíveis com o microgateway na organização associada. Use a configuração a seguir para limitar quais proxies o microgateway vai processar. Por exemplo, essa configuração limita os proxies que o microgateway processará para três: edgemicro_proxy-1, edgemicro_proxy-2 e edgemicro_proxy-3:

edgemicro:
  proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Filtrar produtos por nome

Use a configuração a seguir para limitar o número de produtos de API que o Edge Microgateway baixa e processa. Para filtrar os produtos baixados, adicione o parâmetro de consulta productnamefilter à API /products listada no arquivo *.config.yaml do Edge Microgateway. Exemplo:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

O valor do parâmetro de consulta precisa ser especificado no formato de expressão regular e ter codificação de URL. Por exemplo, a regex ^[Ee]dgemicro.*$ captura nomes como: "edgemicro-test-1" , "edgemicro_demo" e "Edgemicro_New_Demo". O valor codificado em URL, adequado para uso no parâmetro de consulta, é: %5E%5BEe%5Ddgemicro.%2A%24.

A saída de depuração a seguir mostra que apenas os produtos filtrados foram baixados:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Como filtrar produtos por atributos personalizados

Para filtrar produtos com base em atributos personalizados:

Na IU do Edge, selecione o proxy edgemicro_auth na organização/ambiente em que você configurou o Edge Microgateway.
Na guia "Develop", abra a política JavaCallout no editor.
Adicione um atributo personalizado com a chave products.filter.attributes com uma lista separada por vírgulas de nomes de atributos. Somente os produtos que contêm qualquer um dos nomes de atributos personalizados serão retornados ao Edge Microgateway.
Se quiser, desative a verificação para saber se o produto está ativado no ambiente atual definindo o atributo personalizado products.filter.env.enable como false. O padrão é verdadeiro.
(Somente nuvem privada) Se você estiver no Edge para nuvem privada, defina a propriedade org.noncps como true para extrair produtos para ambientes que não são CPS.

Exemplo:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

Filtrar produtos por status de revogação

Os produtos de API têm três códigos de status: "Pendente", "Aprovado" e "Revogado". Uma nova propriedade chamada allowProductStatus foi adicionada à política de definição de variáveis JWT no proxy edgemicro-auth. Para usar essa propriedade para filtrar produtos de API listados no JWT:

Abra o proxy edgemicro-auth no editor de proxy da Apigee.

Adicione a propriedade allowProductStatus ao XML da política SetJWTVariables e especifique uma lista separada por vírgulas de códigos de status para filtrar. Por exemplo, para filtrar por status Pendente e Revogado:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript timeLimit="20000" async="false" continueOnError="false"
    enabled="true" name="Set-JWT-Variables">
    <DisplayName>Set JWT Variables</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="allowProductStatus">Pending,Revoked</Property>
    </Properties>
    <ResourceURL>jsc://set-jwt-variables.js</ResourceURL>
</Javascript>

Se você quiser que apenas os produtos Aprovados sejam listados, defina a propriedade da seguinte maneira:

<Property name="allowProductStatus">Approved</Property>

Salve o proxy.
Se a tag Property não estiver presente, os produtos com todos os códigos de status serão listados no JWT.

Para usar essa nova propriedade, faça upgrade do proxy edgemicro-auth.

Como configurar a frequência de envio de análises

Use esses parâmetros de configuração para controlar a frequência com que o Edge Microgateway envia dados de análise para a Apigee:

bufferSize (opcional): o número máximo de registros de análise que o buffer pode conter antes de começar a descartar os registros mais antigos. Padrão: 10000
batchSize (opcional): o tamanho máximo de um lote de registros de análise enviados à Apigee. Padrão: 500
flushInterval (opcional): o número de milissegundos entre cada liberação de um lote de registros de análise enviados à Apigee. Padrão: 5000

Exemplo:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Como mascarar dados de análise

A configuração a seguir impede que as informações do caminho da solicitação apareçam nas análises do Edge. Adicione o seguinte à configuração do microgateway para mascarar o URI e/ou o caminho da solicitação. O URI consiste nas partes do nome do host e do caminho da solicitação.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Como segregar chamadas de API no Edge Analytics

É possível configurar o plug-in de análise para segregar um caminho de API específico para que ele apareça como um proxy separado nos painéis do Edge Analytics. Por exemplo, é possível separar uma API de verificação de integridade no painel para evitar confundi-la com chamadas de proxy de API reais. No painel do Analytics, os proxies segregados seguem este padrão de nomenclatura:

edgemicro_proxyname-health

A imagem a seguir mostra dois proxies segregados no painel do Analytics: edgemicro_hello-health e edgemicro_mock-health:

Use esses parâmetros para separar caminhos relativos e absolutos no painel do Analytics como proxies separados:

relativePath (opcional): especifica um caminho relativo para segregar no painel do Analytics. Por exemplo, se você especificar /healthcheck, todas as chamadas de API que contêm o caminho /healthcheck vão aparecer no painel como edgemicro_proxyname-health. Essa flag ignora o caminho base do proxy. Para segregar com base em um caminho completo, incluindo o caminho de base, use a flag proxyPath.
proxyPath (opcional): especifica um caminho de proxy de API completo, incluindo o caminho base do proxy, para segregar no painel de análise. Por exemplo, se você especificar /mocktarget/healthcheck, em que /mocktarget é o caminho base do proxy, todas as chamadas de API com o caminho /mocktarget/healthcheck vão aparecer no painel como edgemicro_proxyname-health.

Por exemplo, na configuração a seguir, qualquer caminho de API que contenha /healthcheck será segregado pelo plug-in de análise. Isso significa que /foo/healthcheck e /foo/bar/healthcheck serão segregados como um proxy separado chamado edgemicro_proxyname-health no painel de análise.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Na configuração a seguir, qualquer API com o caminho de proxy /mocktarget/healthcheck será segregada como um proxy separado chamado edgemicro_proxyname-health no painel de análise.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Como configurar o Edge Microgateway atrás de um firewall da empresa

Usar um proxy HTTP para comunicação com o Apigee Edge

Adicionado na versão 3.1.2.

Para usar um proxy HTTP para comunicação entre o Edge Microgateway e o Apigee Edge, faça o seguinte:

Defina as variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Essas variáveis controlam os hosts de cada proxy HTTP que você quer usar para comunicação com o Apigee Edge ou quais hosts não devem processar a comunicação com o Apigee Edge. Exemplo:
```
export HTTP_PROXY='http://localhost:3786'
export HTTPS_PROXY='https://localhost:3786'
export NO_PROXY='localhost,localhost:8080'
```
Observe que NO_PROXY pode ser uma lista de domínios delimitada por vírgulas para os quais o Edge Microgateway não deve fazer proxy.

Para mais informações sobre essas variáveis, consulte https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables
Reinicie o Edge Microgateway.

Usar um proxy HTTP para comunicação de destino

Adicionado na versão 3.1.2.

Para usar um proxy HTTP para comunicação entre o Edge Microgateway e os destinos de back-end, faça o seguinte:

Adicione a seguinte configuração ao arquivo de configuração do microgateway:
```
edgemicro:
  proxy:
    tunnel: true | false
    url: proxy_url
    bypass: target_host # target hosts to bypass the proxy.
    enabled: true | false
```
Em que:
- tunnel: (opcional) quando verdadeiro, o Edge Microgateway usa o método HTTP CONNECT para encapsular solicitações HTTP em uma única conexão TCP. (O mesmo vale se as variáveis de ambiente, conforme mencionado abaixo, para configurar o proxy estiverem ativadas para TLS). Padrão: false
- url: o URL do proxy HTTP.
- bypass: (opcional) especifica um ou mais URLs de host de destino separados por vírgulas que devem ignorar o proxy HTTP. Se essa propriedade não estiver definida, use a variável de ambiente NO_PROXY para especificar quais URLs de destino ignorar.
- enabled: se for verdadeiro e proxy.url estiver definido, use o valor proxy.url para o proxy HTTP. Se for verdadeiro e proxy.url não estiver definido, use os proxies especificados nas variáveis de ambiente de proxy HTTP HTTP_PROXY e HTTPS_PROXY, conforme descrito em Usar um proxy HTTP para comunicação com a Apigee Edge.
Exemplo:
```
edgemicro:
  proxy:
    tunnel: true
    url: 'http://localhost:3786'
    bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
    enabled: true
```
OBSERVAÇÃO: se edgemicro.proxy for omitido do arquivo de configuração ou se edgemicro.proxy.enabled for falso, o Edge Microgateway não usará um proxy HTTP para comunicação de destino.
Reinicie o Edge Microgateway.

Como usar caracteres curinga em proxies compatíveis com o Microgateway

É possível usar um ou mais caracteres curinga "*" no caminho base de um proxy edgemicro_* (compatível com o Microgateway). Por exemplo, um caminho base de /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem que você precise criar novos proxies de API para dar suporte a novas equipes. Observe que /**/ não é compatível.

Importante: a Apigee NÃO é compatível com o uso de um caractere curinga "*" como o primeiro elemento de um caminho base. Por exemplo, isto NÃO é compatível: pesquisa /*/.

Como alternar chaves JWT

Como o Edge Microgateway usa JWTs

O JSON Web Token (JWT) é um padrão de token descrito no RFC7519. O JWT oferece uma maneira de assinar um conjunto de declarações, que podem ser verificadas de maneira confiável pelo destinatário do JWT.

É possível gerar um JWT usando a CLI e usá-lo no cabeçalho de autorização das chamadas de API em vez de uma chave de API. Exemplo:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Para saber como gerar JWTs com a CLI, consulte Gerar um token.

O que é rotação de chaves?

Depois de gerar um JWT, talvez seja necessário alterar o par de chaves pública/privada armazenado no KVM criptografado do Edge. Esse processo de geração de um novo par de chaves é chamado de rotação de chaves. Quando você faz a rotação de chaves, um novo par de chaves pública/privada é gerado e armazenado na KVM "microgateway" na organização/ambiente do Apigee Edge. Além disso, a chave pública antiga é mantida com o valor do ID da chave original.

Para gerar um JWT, o Edge usa informações armazenadas no KVM criptografado. Um KVM chamado microgateway foi criado e preenchido com chaves quando você configurou inicialmente o Edge Microgateway. As chaves no KVM são usadas para assinar e criptografar um JWT.

As chaves do KVM incluem:

private_key: a chave privada RSA mais recente (criada mais recentemente) usada para assinar JWTs.
public_key: o certificado mais recente (criado mais recentemente) usado para verificar JWTs assinados com a private_key.
private_key_kid: o ID da chave privada mais recente (criada mais recentemente). Esse ID de chave está associado ao valor private_key e é usado para dar suporte à rotação de chaves.
public_key1_kid: o ID da chave pública mais recente (criada mais recentemente). Essa chave está associada ao valor public_key1 e é usada para dar suporte à rotação de chaves. Esse valor é o mesmo que o kid da chave privada.
public_key1: a chave pública mais recente (criada mais recentemente).

Quando você realiza a rotação de chaves, os valores de chave atuais são substituídos no mapa, e novas chaves são adicionadas para reter as chaves públicas antigas. Exemplo:

public_key2_kid: o ID da chave pública antiga. Essa chave está associada ao valor public_key2 e é usada para oferecer suporte à rotação de chaves.
public_key2: a chave pública antiga.

Os JWTs apresentados para verificação serão verificados usando a nova chave pública. Se a verificação falhar, a chave pública antiga será usada até que o JWT expire (após o intervalo token_expiry*, padrão de 30 minutos). Dessa forma, é possível "alternar" as chaves sem interromper imediatamente o tráfego da API.

Como fazer a rotação de chaves

Nesta seção, explicamos como realizar uma rotação de chaves.

Para fazer upgrade da KVM, use o comando edgemicro upgradekvm. Para detalhes sobre como executar esse comando, consulte Como fazer upgrade da KVM. Você só precisa fazer isso uma vez.
Para fazer upgrade do proxy edgemicro-oauth, use o comando edgemicro upgradeauth. Para detalhes sobre como executar esse comando, consulte Como fazer upgrade do proxy edgemicro-auth. Você só precisa fazer isso uma vez.
Adicione a seguinte linha ao arquivo ~/.edgemicro/org-env-config.yaml, em que você precisa especificar a mesma organização e o mesmo ambiente que configurou para o microgateway usar:
```
jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'
```

Execute o comando de rotação de chaves para alternar as chaves. Para detalhes sobre esse comando, consulte Como alternar chaves.

edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

Exemplo:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47

Após a rotação de chaves, o Edge retorna várias chaves para o Edge Microgateway. No exemplo a seguir, cada chave tem um valor "kid" (ID da chave) exclusivo. Em seguida, o microgateway usa essas chaves para validar os tokens de autorização. Se a validação do token falhar, o microgateway vai verificar se há uma chave mais antiga no conjunto de chaves e vai testá-la. O formato das chaves retornadas é JSON Web Key (JWK). Leia sobre esse formato em RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Como configurar um atraso "não antes de"

Nas versões 3.1.5 e anteriores, a nova chave privada gerada pelo comando rotatekey entrava em vigor imediatamente, e os novos tokens gerados eram assinados com a nova chave privada. No entanto, a nova chave pública só era disponibilizada para instâncias do Edge Microgateway a cada 10 minutos (por padrão) quando a configuração do microgateway era atualizada. Devido a esse atraso entre a assinatura do token e a atualização da instância do microgateway, os tokens assinados com a chave mais recente seriam rejeitados até que todas as instâncias recebessem a chave pública mais recente.

Nos casos em que há várias instâncias do microgateway, o atraso da chave pública às vezes resultava em erros de tempo de execução intermitentes com o status 403, porque a validação do token era transmitida em uma instância, mas falhava em outra até que todas as instâncias fossem atualizadas.

A partir da versão 3.1.6, uma nova flag no comando rotatekey permite especificar um atraso para que a nova chave privada entre em vigor, permitindo que todas as instâncias do microgateway sejam atualizadas e recebam a nova chave pública. A nova flag é --nbf, que significa "não antes". Essa flag usa um valor inteiro, que é o número de minutos de atraso.

No exemplo a seguir, o atraso é definido como 15 minutos:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

Uma boa prática é definir o atraso para ser maior do que a configuração config_change_poll_internal, que é de 10 minutos por padrão. Consulte também Atributos do edgemicro.

Como filtrar proxies baixados

Por padrão, o Edge Microgateway faz o download de todos os proxies na sua organização do Edge que começam com o prefixo de nomenclatura "edgemicro_". É possível alterar esse padrão para fazer o download de proxies com nomes que correspondam a um padrão.

Abra o arquivo de configuração do Edge Micro: ~/.edgemicro/org-env-config.yaml
Adicione o elemento proxyPattern em edge_config. Por exemplo, o padrão a seguir fará o download de proxies como edgemicro_foo, edgemicro_fast e edgemicro_first.
```
edge_config:
…
proxyPattern: edgemicro_f*
```

Como especificar produtos sem proxies de API

No Apigee Edge, é possível criar um produto de API que não contenha proxies de API. Essa configuração de produto permite que uma chave de API associada a esse produto funcione com qualquer proxy implantado na sua organização. A partir da versão 2.5.4, o Edge Microgateway é compatível com essa configuração de produto.

Como depurar e solucionar problemas

Como se conectar a um depurador

É possível executar o Edge Microgateway com um depurador, como o node-inspector. Isso é útil para solucionar problemas e depurar plug-ins personalizados.

Reinicie o Edge Microgateway no modo de depuração. Para fazer isso, adicione DEBUG=* ao início do comando start:
```
DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET
```
OBSERVAÇÃO: no Windows, use SET DEBUG=*

Para direcionar a saída de depuração para um arquivo, use este comando:
```
export DEBUG=* nohup edgemicro start \
-o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log
```
Inicie o depurador e configure-o para detectar o número da porta do processo de depuração.
Agora é possível percorrer o código do Edge Microgateway, definir pontos de interrupção, observar expressões e assim por diante.

É possível especificar flags padrão do Node.js relacionadas ao modo de depuração. Por exemplo, --nolazy ajuda na depuração de código assíncrono.

Como verificar arquivos de registro

Se você estiver com problemas, examine os arquivos de registro para ver detalhes de execução e informações de erro. Para mais detalhes, consulte Como gerenciar arquivos de registro.

Como usar a segurança da chave de API

As chaves de API fornecem um mecanismo simples para autenticar clientes que fazem solicitações ao Edge Microgateway. Para receber uma chave de API, copie o valor do token do cliente (também chamado de ID do cliente) de um produto da Apigee Edge que inclua o proxy de autenticação do Edge Microgateway.

Armazenamento de chaves em cache

As chaves de API são trocadas por tokens do portador, que são armazenados em cache. Para desativar o armazenamento em cache, defina o cabeçalho Cache-Control: no-cache nas solicitações recebidas para o Edge Microgateway.

Como usar uma chave de API

É possível transmitir a chave de API em uma solicitação de API como um parâmetro de consulta ou em um cabeçalho. Por padrão, o nome do cabeçalho e do parâmetro de consulta é x-api-key.

Exemplo de parâmetro de consulta:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Exemplo de cabeçalho:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Como configurar o nome da chave de API

Por padrão, x-api-key é o nome usado para o cabeçalho da chave de API e o parâmetro de consulta. É possível mudar esse padrão no arquivo de configuração, conforme explicado em Como fazer mudanças na configuração. Por exemplo, para alterar o nome para apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

Neste exemplo, o parâmetro de consulta e o nome do cabeçalho são alterados para apiKey. O nome x-api-key não vai mais funcionar em nenhum dos casos. Consulte também Como fazer alterações na configuração.

Exemplo:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Para mais informações sobre como usar chaves de API com solicitações de proxy, consulte Proteger o Edge Microgateway.

Ativar códigos de resposta upstream

Por padrão, o plug-in oauth retorna apenas códigos de status de erro 4xx se a resposta não for um status 200. É possível mudar esse comportamento para que ele sempre retorne o código 4xx ou 5xx exato, dependendo do erro.

Para ativar esse recurso, adicione a propriedade oauth.useUpstreamResponse: true à configuração do Edge Microgateway. Exemplo:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Como usar a segurança de tokens do OAuth2

Nesta seção, explicamos como receber tokens de acesso e de atualização do OAuth2. Os tokens de acesso são usados para fazer chamadas de API seguras pelo microgateway. Os tokens de atualização são usados para receber novos tokens de acesso.

Como receber um token de acesso

Nesta seção, explicamos como usar o proxy edgemicro-auth para receber um token de acesso.

Também é possível receber um token de acesso usando o comando da CLI edgemicro token. Para detalhes sobre a CLI, consulte Como gerenciar tokens.

API 1: enviar credenciais como parâmetros do corpo

Substitua os nomes da organização e do ambiente no URL e substitua os valores do ID do consumidor e da chave secreta do consumidor recebidos de um app de desenvolvedor no Apigee Edge pelos parâmetros de corpo client_id e client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: enviar credenciais em um cabeçalho de autenticação básica

Envie as credenciais do cliente como um cabeçalho de autenticação básica e o grant_type como um parâmetro de formulário. Esse formato de comando também é discutido em RFC 6749: The OAuth 2.0 Authorization Framework.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Exemplo de resposta

A API retorna uma resposta JSON. Não há diferença entre as propriedades token e access_token. Você pode usar qualquer um deles. Observe que expires_in é um valor inteiro especificado em segundos.

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 1799
}

Como receber um token de atualização

Para receber um token de atualização, faça uma chamada de API para o endpoint /token do proxy edgemicro-auth. Você PRECISA fazer essa chamada de API com o tipo de permissão de acesso password. As etapas a seguir mostram o processo.

Receba um token de acesso e de atualização com a API /token. Observe que o tipo de permissão de acesso é password:

curl -X POST \
  https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
   "client_secret":"bUdDcFgv3nXffnU",
   "grant_type":"password",
   "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
   "password":"bUdD2FvnMsXffnU"
}'

A API retorna um token de acesso e um token de atualização. A resposta será semelhante a esta. Os valores de expires_in são números inteiros e são especificados em segundos.

{
    "token": "your-access-token",
    "access_token": "your-access-token",
    "token_type": "bearer",
    "expires_in": 108,
    "refresh_token": "your-refresh-token",
    "refresh_token_expires_in": 431,
    "refresh_token_issued_at": "1562087304302",
    "refresh_token_status": "approved"
}

Agora você pode usar o token de atualização para receber um novo token de acesso chamando o endpoint /refresh da mesma API. Exemplo:

curl -X POST \
  https://willwitman-test.apigee.net/edgemicro-auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{
   "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
   "client_secret":"bUdDc2Fv3nMXffnU",
   "grant_type":"refresh_token",
   "refresh_token":"your-refresh-token"
}'

A API retorna um novo token de acesso. A resposta será semelhante a esta:

{
    "token": "your-new-access-token"
    }

Monitoramento contínuo

O Forever é uma ferramenta do Node.js que reinicia automaticamente um app Node.js caso o processo seja interrompido ou tenha um erro. O Edge Microgateway tem um arquivo forever.json que pode ser configurado para controlar quantas vezes e com quais intervalos o Edge Microgateway precisa ser reiniciado. Esse arquivo configura um serviço Forever chamado forever-monitor, que gerencia o Forever de maneira programática.

O arquivo forever.json está no diretório raiz de instalação do Edge Microgateway. Consulte Onde o Edge Microgateway está instalado. Para detalhes sobre as opções de configuração, consulte a documentação do forever-monitor.

O comando edgemicro forever inclui flags que permitem especificar o local do arquivo forever.json (a flag -f) e iniciar/interromper o processo de monitoramento Forever (a flag -a). Exemplo:

edgemicro forever -f ~/mydir/forever.json -a start

Para mais informações, consulte Monitoramento contínuo na referência da CLI.

Como especificar um endpoint de arquivo de configuração

Se você executar várias instâncias do Edge Microgateway, talvez queira gerenciar as configurações delas em um único local. Para fazer isso, especifique um endpoint HTTP em que o Edge Micro possa fazer o download do arquivo de configuração. É possível especificar esse endpoint ao iniciar o Edge Micro usando a sinalização -u.

Exemplo:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

em que o endpoint mgconfig retorna o conteúdo do arquivo de configuração. Esse é o arquivo que, por padrão, está localizado em ~/.edgemicro e tem a convenção de nomenclatura: org-env-config.yaml.

Como desativar o armazenamento em buffer de dados de conexão TCP

É possível usar o atributo de configuração nodelay para desativar o armazenamento em buffer de dados para conexões TCP usadas pelo Edge Microgateway.

Por padrão, as conexões TCP usam o algoritmo de Nagle para armazenar dados em buffer antes de enviá-los. Definir nodelay como true desativa esse comportamento (os dados serão disparados imediatamente sempre que socket.write() for chamado). Consulte também a documentação do Node.js para mais detalhes.

Para ativar o nodelay, edite o arquivo de configuração do Edge Micro da seguinte maneira:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Como executar o Edge Microgateway no modo independente

É possível executar o Edge Microgateway completamente desconectado de qualquer dependência do Apigee Edge. Esse cenário, chamado de modo independente, permite executar e testar o Edge Microgateway sem uma conexão de Internet.

No modo independente, os recursos a seguir não funcionam, porque exigem conexão com o Apigee Edge:

OAuth e chave de API
Cota
Analytics

Por outro lado, os plug-ins personalizados e o Spike Arrest funcionam normalmente, porque não exigem uma conexão com o Apigee Edge. Além disso, um novo plug-in chamado extauth permite autorizar chamadas de API para o microgateway com um JWT no modo independente.

Como configurar e iniciar o gateway

Para executar o Edge Microgateway no modo independente:

Crie um arquivo de configuração com o seguinte nome: $HOME/.edgemicro/$ORG-$ENV-config.yaml
Você pode usar os valores que quiser para $ORG e $ENV no nome do arquivo. A combinação de organização/ambiente é simplesmente uma convenção que permite ao Edge Microgateway encontrar o arquivo quando ele é iniciado.

Exemplo:
```
vi $HOME/.edgemicro/foo-bar-config.yaml
```
Cole o código a seguir no arquivo:
```
edgemicro:
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - extauth
      - spikearrest
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
extauth:
  publickey_url: https://www.googleapis.com/oauth2/v1/certs
spikearrest:
  timeUnit: second
  allow: 10
  buffersize: 0
```
O arquivo de configuração contém um plug-in especial e opcional chamado extauth. Esse plug-in verifica um token JWT válido transmitido ao microgateway. Em uma etapa posterior, você vai aprender a receber e usar o token. Além disso, observe que o plug-in spikearrest está incluído porque não depende da conectividade com o Edge. Os plug-ins quota, oauth e analytics são excluídos porque dependem da conectividade com o Edge e não funcionam no modo desconectado. Plug-ins personalizados são permitidos e vão funcionar conforme o esperado.
Exporte a seguinte variável de ambiente com o valor "1":
```
export EDGEMICRO_LOCAL=1
```
Execute o seguinte comando start, em que você fornece valores para instanciar o proxy local:
```
edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
  -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH
```
Em que:
- $ORG é o nome da "organização" que você usou no nome do arquivo de configuração.
- $ENV é o nome "env" usado no nome do arquivo de configuração.
- $LOCAL_PROXY_NAME é o nome do proxy local que será criado. Use o nome que preferir.
- $LOCAL_PROXY_VERSION é o número da versão do proxy.
- $TARGET_URL é o URL do destino do proxy. O destino é o serviço que o proxy chama.
- $BASE_PATH é o caminho base do proxy. Esse valor precisa começar com uma barra. Para um caminho base raiz, especifique apenas uma barra, por exemplo, "/".
Exemplo:
```
edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
```
Testar a configuração.
```
curl http://localhost:8000/echo  { "error" : "missing_authorization" }
```
Como o plug-in extauth está no arquivo foo-bar-config.yaml, você recebe um erro "missing_authorization". Esse plug-in valida um JWT que precisa estar presente no cabeçalho de autorização da chamada de API. Na próxima seção, você vai receber um JWT que permitirá que as chamadas de API sejam feitas sem o erro.

Exemplo: como receber um token de autorização

O exemplo a seguir mostra como receber um JWT do endpoint JWT do Edge Microgateway no Apigee Edge (edgemicro-auth/jwkPublicKeys). Esse endpoint é implantado quando você realiza uma configuração padrão do Edge Microgateway. Para receber o JWT do endpoint da Apigee, primeiro é necessário fazer a configuração padrão do Edge Microgateway e estar conectado à Internet. O endpoint da Apigee é usado aqui apenas para fins de exemplo e não é obrigatório. Se quiser, use outro endpoint de token JWT. Se você fizer isso, precisará receber o JWT usando a API fornecida para esse endpoint.

A inclusão do plug-in extauth na configuração do microgateway é opcional, mas, se você o incluir, será necessário fornecer um token JWT válido no cabeçalho de autorização para chamadas de API.

As etapas a seguir explicam como receber um token usando o endpoint edgemicro-auth/jwkPublicKeys:

É preciso realizar uma configuração padrão do Edge Microgateway para implantar o proxy edgemicro-auth na sua organização/ambiente no Apigee Edge. Se você já fez isso, não precisa repetir.
Se você implantou o Edge Microgateway na nuvem da Apigee, precisa se conectar à Internet para receber um JWT desse endpoint.
Interrompa o Edge Microgateway:
```
edgemicro stop
```
No arquivo de configuração que você criou anteriormente ($HOME/.edgemicro/org-env-config.yaml), aponte o atributo extauth:publickey_url para o endpoint edgemicro-auth/jwkPublicKeys na organização/ambiente da Apigee Edge. Exemplo:
```
extauth:
  publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'
```
Reinicie o Edge Microgateway como você fez anteriormente, usando os nomes de organização/ambiente que você usou no nome do arquivo de configuração. Exemplo:
```
edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /
```
Receba um token JWT do endpoint de autorização. Como você está usando o endpoint edgemicro-auth/jwkPublicKeys, é possível usar este comando da CLI:
Para esta etapa, você vai precisar de uma conexão de Internet. O comando a seguir busca um token da Apigee Edge. Para realizar essa etapa, você precisa ter uma organização da Apigee em que tenha realizado uma configuração padrão do Edge Microgateway. Depois de concluir essa etapa, não é necessário estar conectado à Internet. O token vai continuar funcionando no modo independente até expirar.

É possível gerar um JWT para o Edge Microgateway usando o comando edgemicro token ou uma API. Exemplo:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Em que:

your_org é o nome da organização da Apigee para que você configurou anteriormente o Edge Microgateway.
your_env é um ambiente na organização.
A opção i especifica o token do cliente de um app de desenvolvedor que tem um produto que inclui o proxy edgemicro-auth.
A opção s especifica a chave secreta do consumidor de um app de desenvolvedor que tem um produto que inclui o proxy edgemicro-auth.

Esse comando solicita que a Apigee Edge gere um JWT que pode ser usado para verificar chamadas de API.

Consulte também Gerar um token.

Testar a configuração independente

Para testar a configuração, chame a API com o token adicionado no cabeçalho de autorização da seguinte maneira:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Exemplo:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Exemplo de saída:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Como usar o modo de proxy local

No modo de proxy local, o Edge Microgateway não exige que um proxy compatível com o microgateway seja implantado no Apigee Edge. Em vez disso, você configura um "proxy local" fornecendo um nome de proxy local, um caminho base e um URL de destino ao iniciar o microgateway. As chamadas de API para o microgateway são enviadas ao URL de destino do proxy local. Em todos os outros aspectos, o modo de proxy local funciona exatamente da mesma forma que a execução do Edge Microgateway no modo normal. A autenticação funciona da mesma forma, assim como a interrupção de picos e a aplicação de cotas, os plug-ins personalizados etc.

As duas diferenças importantes entre o modo local e a configuração normal do Edge Microgateway são: (1) no modo local, não é necessário criar um proxy compatível com o Microgateway no Apigee Edge e (2) ao criar um produto de API no Edge, é preciso adicionar apenas um proxy a ele, o proxy edgemicro-auth. Não é necessário adicionar outros proxies ao produto.

Caso de uso e exemplo

O modo de proxy local é útil quando você só precisa associar um único proxy a uma instância do Edge Microgateway. Por exemplo, é possível injetar o Edge Microgateway no Kubernetes como um proxy sidecar, em que um microgateway e um serviço são executados em um único pod e em que o microgateway gerencia o tráfego de e para o serviço complementar. A figura a seguir ilustra essa arquitetura em que o Edge Microgateway funciona como um proxy sidecar em um cluster do Kubernetes. Cada instância do microgateway se comunica apenas com um único endpoint no serviço complementar:

Edgemicro como arquivo secundário

Um benefício desse estilo de arquitetura é que o Edge Microgateway fornece gerenciamento de APIs para serviços individuais implantados em um ambiente de contêiner, como um cluster do Kubernetes.

Como configurar o modo de proxy local

Para configurar o Edge Microgateway para ser executado no modo de proxy local, siga estas etapas:

Execute edgemicro init para configurar o ambiente de configuração local, exatamente como você faria em uma configuração típica do Edge Microgateway. Consulte também Configurar o Edge Microgateway.
Execute edgemicro configure, como faria em um procedimento de configuração típico do Edge Microgateway. Exemplo:
```
edgemicro configure -o your_org -e your_env -u your_apigee_username
```
Esse comando implanta a política edgemicro-auth no Edge e retorna uma chave e um secret que você precisará para iniciar o microgateway. Se precisar de ajuda, consulte Configurar o Edge Microgateway.
Na Apigee Edge, crie um produto de API com os seguintes requisitos de configuração obrigatórios (é possível gerenciar todas as outras configurações como quiser):
- Você precisa adicionar o proxy edgemicro-auth ao produto. Esse proxy foi implantado automaticamente quando você executou edgemicro configure.
- Você precisa fornecer um caminho de recurso. A Apigee recomenda adicionar este caminho ao produto: /**. Para saber mais, consulte Como configurar o comportamento do caminho do recurso. Consulte também Criar produtos de API na documentação do Edge.
Na Apigee Edge, crie um desenvolvedor ou use um desenvolvedor atual, se quiser. Para receber ajuda, consulte Como adicionar desenvolvedores usando a IU de gerenciamento do Edge.
No Apigee Edge, crie um app de desenvolvedor. Você precisa adicionar o produto de API que acabou de criar ao app. Para receber ajuda, consulte Como registrar um app na IU de gerenciamento do Edge.
Na máquina em que o Edge Microgateway está instalado, exporte a seguinte variável de ambiente com o valor "1".
```
export EDGEMICRO_LOCAL_PROXY=1
```
Execute o seguinte comando start:
```
edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
    -a local_proxy_name -v local_proxy_version -t target_url -b base_path
```
Em que:
- your_org é sua organização da Apigee.
- your_environment é um ambiente na organização.
- your_key é a chave retornada quando você executou edgemicro configure.
- your_secret é o secret retornado quando você executou edgemicro configure.
- local_proxy_name é o nome do proxy local que será criado.
- local_proxy_version é o número da versão do proxy.
- target_url é o URL do destino do proxy (o serviço que o proxy vai chamar).
- base_path é o caminho base do proxy. Esse valor precisa começar com uma barra. Para um caminho base raiz, especifique apenas uma barra, por exemplo, "/".
Exemplo:
```
edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
  -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
  -t http://mocktarget.apigee.net -b /echo
```

Como testar a configuração

Para testar a configuração do proxy local, chame o endpoint do proxy. Por exemplo, se você especificou um caminho base de /echo, poderá chamar o proxy da seguinte maneira:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Essa chamada de API inicial produziu um erro porque você não forneceu uma chave de API válida. Você encontra a chave no app de desenvolvedor que criou anteriormente. Abra o app na IU do Edge, copie o token do cliente e use-o da seguinte maneira:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Exemplo:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Exemplo de saída:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

Como usar o sincronizador

Nesta seção, explicamos como usar o sincronizador, um recurso opcional que melhora a resiliência do Edge Microgteway, permitindo que ele recupere dados de configuração do Apigee Edge e os grave em um banco de dados local do Redis. Com uma instância do sincronizador em execução, outras instâncias do Edge Microgateway em execução em nós diferentes podem recuperar a configuração diretamente desse banco de dados.

No momento, o recurso de sincronização é compatível com o Redis 5.0.x.

O que é o sincronizador?

O sincronizador oferece um nível de resiliência para o Edge Microgateway. Isso ajuda a garantir que cada instância do Edge Microgateway use a mesma configuração e que, no caso de uma interrupção da Internet, as instâncias do Edge Microgateway possam ser iniciadas e executadas corretamente.

Por padrão, as instâncias do Edge Microgateway precisam se comunicar com o Apigee Edge para recuperar e atualizar os dados de configuração, como as configurações de proxy e produto de API. Se a conexão de Internet com o Edge for interrompida, as instâncias do microgateway poderão continuar funcionando porque os dados de configuração mais recentes estão armazenados em cache. No entanto, novas instâncias do microgateway não podem ser iniciadas sem uma conexão clara. Além disso, é possível que uma interrupção da Internet resulte em uma ou mais instâncias do microgateway em execução com informações de configuração que não estão sincronizadas com outras instâncias.

O sincronizador do Edge Microgateway oferece um mecanismo alternativo para que as instâncias do Edge Microgateway recuperem os dados de configuração necessários para iniciar e processar o tráfego de proxy de API. Os dados de configuração recuperados de chamadas para o Apigee Edge incluem: a chamada jwk_public_keys, a chamada jwt_public_key, a chamada de inicialização e a chamada de produtos de API. O sincronizador permite que todas as instâncias do Edge Microgateway em execução em nós diferentes sejam iniciadas corretamente e permaneçam sincronizadas, mesmo que a conexão de Internet entre o Edge Microgateway e o Apigee Edge seja interrompida.

O sincronizador é uma instância especialmente configurada do Edge Microgateway. A única finalidade dele é consultar a Apigee Edge (o tempo é configurável), recuperar dados de configuração e gravá-los em um banco de dados local do Redis. A instância do sincronizador não pode processar o tráfego do proxy de API. Outras instâncias do Edge Microgateway em execução em nós diferentes podem ser configuradas para recuperar dados de configuração do banco de dados do Redis, em vez do Apigee Edge. Como todas as instâncias do microgateway extraem os dados de configuração do banco de dados local, elas podem iniciar e processar solicitações de API mesmo em caso de interrupção da Internet.

Como configurar uma instância do sincronizador

Adicione a seguinte configuração ao arquivo org-env/config.yaml para a instalação do Edge Microgateway que você quer usar como sincronizador:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Exemplo:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Opção	Descrição
`redisHost`	O host em que a instância do Redis está em execução. Padrão: 127.0.0.1
`redisPort`	A porta da instância do Redis. Padrão: 6379
`redisDb`	O banco de dados do Redis que será usado. Padrão: 0
`redisPassword`	A senha do banco de dados.

É possível usar a variável de ambiente EDGEMICRO_REDIS_PASSWORD para substituir o parâmetro edgemicro.redisPassword. Consulte também Como definir atributos de configuração com valores de variáveis de ambiente.

Por fim, salve o arquivo de configuração e inicie a instância do Edge Microgateway. Ele começará a pesquisar a Apigee Edge e armazenar os dados de configuração baixados no banco de dados do Redis.

Como configurar instâncias regulares do Edge Microgateway

Com o sincronizador em execução, é possível configurar outros nós do Edge Microgateway para executar instâncias regulares do microgateway que processam o tráfego de proxy de API. No entanto, você configura essas instâncias para receber os dados de configuração do banco de dados do Redis, em vez do Apigee Edge.

Adicione a seguinte configuração ao arquivo org-env/config.yaml de cada nó adicional do Edge Microgateway. A propriedade synchronizerMode está definida como 0. Essa propriedade define a instância para operar como uma instância normal do Edge Microgateway que processa o tráfego de proxy de API, e a instância vai receber os dados de configuração do banco de dados do Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Exemplo:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Propriedades de configuração

As seguintes propriedades de configuração foram adicionadas para permitir o uso do sincronizador:

Atributo Valores Descrição

Atributo	Valores	Descrição
`edge_config.synchronizerMode`	0 ou 1	Se for 0 (o padrão), o Edge Microgateway vai operar no modo padrão. Se for 1, inicie a instância do Edge Microgateway para operar como um sincronizador. Nesse modo, a instância extrai dados de configuração da Apigee Edge e os armazena em um banco de dados Redis local. Essa instância não pode processar solicitações de proxy de API. O único propósito dela é consultar o Apigee Edge para receber dados de configuração e gravá-los no banco de dados local. Em seguida, configure outras instâncias do microgateway para ler o banco de dados.
`edge_config.redisBasedConfigCache`	verdadeiro ou falso	Se for verdadeiro, a instância do Edge Microgateway vai buscar os dados de configuração no banco de dados do Redis, em vez de no Apigee Edge. O banco de dados do Redis precisa ser o mesmo em que o sincronizador está configurado para gravar. Se o banco de dados do Redis estiver indisponível ou vazio, o microgateway vai procurar um arquivo `cache-config.yaml` para a configuração. Se for falso (o padrão), a instância do Edge Microgateway buscará dados de configuração do Apigee Edge como de costume.
`edgemicro.config_change_poll_interval`	Intervalo de tempo, em segundos	Especifica o intervalo de pesquisa para o sincronizador extrair dados do Apigee Edge.

edge_config.synchronizerMode

0 ou 1

Se for 0 (o padrão), o Edge Microgateway vai operar no modo padrão.

Se for 1, inicie a instância do Edge Microgateway para operar como um sincronizador. Nesse modo, a instância extrai dados de configuração da Apigee Edge e os armazena em um banco de dados Redis local. Essa instância não pode processar solicitações de proxy de API. O único propósito dela é consultar o Apigee Edge para receber dados de configuração e gravá-los no banco de dados local. Em seguida, configure outras instâncias do microgateway para ler o banco de dados.

edge_config.redisBasedConfigCache

verdadeiro ou falso

Se for verdadeiro, a instância do Edge Microgateway vai buscar os dados de configuração no banco de dados do Redis, em vez de no Apigee Edge. O banco de dados do Redis precisa ser o mesmo em que o sincronizador está configurado para gravar. Se o banco de dados do Redis estiver indisponível ou vazio, o microgateway vai procurar um arquivo cache-config.yaml para a configuração.

Se for falso (o padrão), a instância do Edge Microgateway buscará dados de configuração do Apigee Edge como de costume.

edgemicro.config_change_poll_interval Intervalo de tempo, em segundos Especifica o intervalo de pesquisa para o sincronizador extrair dados do Apigee Edge.

Como configurar URLs de exclusão para plug-ins

É possível configurar o microgateway para pular o processamento de plug-ins para URLs especificados. É possível configurar esses URLs de "exclusão" globalmente (para todos os plug-ins) ou para plug-ins específicos.

Exemplo:

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

Neste exemplo, os plug-ins não vão processar chamadas de proxy de API recebidas com os caminhos /hello ou /proxy_one. Além disso, o plug-in json2xml será ignorado para APIs com /hello/xml no caminho.

Não é possível excluir o plug-in analytics.

Como definir atributos de configuração com valores de variáveis de ambiente

É possível especificar variáveis de ambiente usando tags no arquivo de configuração. As tags de variáveis de ambiente especificadas são substituídas pelos valores reais das variáveis de ambiente. As substituições são armazenadas apenas na memória, não nos arquivos de configuração ou de cache originais.

Observação: por padrão, a tag <E> analisa os valores das variáveis como strings. Para especificar valores inteiros positivos e booleanos, use as tags internas <n> e <b>, conforme ilustrado nos exemplos abaixo.

Neste exemplo, o atributo key é substituído pelo valor da variável de ambiente TARGETS_SSL_CLIENT_KEY e assim por diante.

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

Neste exemplo, a tag <n> é usada para indicar um valor inteiro. Somente números inteiros positivos são aceitos.

edgemicro:
  port: <E><n>EMG_PORT</n></E>

Neste exemplo, a tag <b> é usada para indicar um valor booleano ( ou seja, verdadeiro ou falso).

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>