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

1. Execute o seguinte comando npm para fazer upgrade para a versão mais recente do Edge Microgateway:

   npm upgrade edgemicro -g

   Para fazer upgrade para uma versão específica do Edge Microgateway, especifique o número da versão no comando de upgrade. Se você não especificar o número da versão, a versão mais recente será instalada. Por exemplo, para fazer upgrade para a versão 2.5.26, use o seguinte comando:

   npm upgrade edgemicro@2.5.26 -g

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

   edgemicro --version
   current nodejs version is v8.9.0
   current edgemicro version is 2.5.26
       

3. Por fim, faça upgrade para a versão mais recente do proxy edgemicro-auth:

   edgemicro upgradeauth -o org_name -e env_name -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):

1. Atualize a configuração do Edge Microgateway:

   edgemicro reload -o org_name -e env_name -k key -s secret

   Em que:

   • org_name é o nome da sua organização do Edge (você precisa ser um administrador da organização).
   • env_name é 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:

1. Reinicie o Edge Microgateway:

   edgemicro start -o org_name -e env_name -k key -s secret

   Em que:

   • org_name é o nome da sua organização do Edge (você precisa ser um administrador da organização).
   • env_name é 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

É 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:

1. Gere ou consiga um certificado SSL e uma chave usando o utilitário openssl ou o método que preferir.
2. 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

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

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.

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

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

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

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. Por padrão, o URL desse proxy é especificado no arquivo de configuração do Edge Microgateway da seguinte maneira:

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.

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

É possível definir estes níveis de registro: info, warn e error. O nível de informações é recomendado. Ele registra todas as solicitações de API e respostas, e é o padrão.

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

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 três tipos de arquivos de registro:

• api: registra todas as solicitações e respostas que fluem pelo Edge Microgateway. Os contadores (estatísticas) e erros da API também são registrados nesse arquivo.
• err: registra tudo o que é enviado para stderr.
• out: registra tudo o que é enviado para stdout.

Esta é a convenção de nomenclatura:

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

Exemplo:

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.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 os arquivos de registro, defina o DEBUG=* ao iniciar o Edge Microgateway. Exemplo:

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

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: depende do contexto. Pode ser info, warn ou error, dependendo do nível de registro. Pode ser "stats" para um registro de estatísticas, "warn" para avisos ou "error" para erros.
• 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: depende do contexto. Pode ser info, warn ou error, dependendo do nível de registro. Pode ser "stats" para um registro de estatísticas, "warn" para avisos ou "error" para erros.
• 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: depende do contexto. Pode ser info, warn ou error, dependendo do nível de registro. Pode ser "stats" para um registro de estatísticas, "warn" para avisos ou "error" para erros.
• 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: depende do contexto. Pode ser info, warn ou error, dependendo do nível de registro. Pode ser "stats" para um registro de estatísticas, "warn" para avisos ou "error" para erros.
• 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.

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: 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.
  • 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)

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)
• 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:

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

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

Compatível com v2.4.x

Se o Edge Microgateway estiver instalado atrás de um firewall, talvez ele não consiga se comunicar com o Apigee Edge. Nesse caso, há duas opções:

Opção 1:

A primeira opção é definir a opção edgemicro: proxy_tunnel como verdadeira no arquivo de configuração do microgateway:

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

Quando proxy_tunnel é true, 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 para configurar o proxy estiverem com o TLS ativado.

Opção 2:

A segunda opção é especificar um proxy e definir proxy_tunnel como false no arquivo de configuração do microgateway. Exemplo:

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

Nesse caso, é possível definir as seguintes variáveis para controlar os hosts de cada proxy HTTP que você quer usar ou quais hosts não devem processar proxies do Edge Microgateway: HTTP_PROXY, HTTPS_PROXY e NO_PROXY.

É possível definir NO_PROXY como uma lista de domínios delimitada por vírgulas para os quais o Edge Microgateway não deve fazer proxy. Exemplo:

export NO_PROXY='localhost,localhost:8080'

Defina HTTP_PROXY e HTTPS_PROXY como o endpoint de proxy HTTP para que o Edge Microgateway possa enviar mensagens para ele. Exemplo:

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

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

Consulte também

Como configurar o Edge Microgateway atrás de um firewall corporativo na comunidade da Apigee.

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

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.

Como o Edge Microgateway usa o JWT

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.

O Edge Microgateway usa JWTs como tokens do portador para segurança do OAuth. Ao gerar um token OAuth para o Edge Microgateway, você recebe um JWT de volta. Em seguida, use o JWT no cabeçalho de autorização das chamadas de API. Exemplo:

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

Como gerar um novo JWT

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

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Esse comando solicita que a Apigee Edge gere um JWT que pode ser usado para verificar chamadas de API. Os parâmetros -i e -s são o ID do consumidor e os valores de chave secreta de um app de desenvolvedor na sua organização da Apigee Edge.

Ou você também pode gerar um JWT usando a API Management:

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your consumer key",
    "client_secret": "your consumer secret",
    "grant_type": "client_credentials"
  }'

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").
• client_id é o ID do consumidor no app de desenvolvedor que você criou anteriormente.
• client_secret é a chave secreta do consumidor no app de desenvolvedor que você criou anteriormente.

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é expirar (após 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.

Se você configurou sua instância do Edge Microgateway antes da versão 2.5.2

Se você configurou sua instância do Edge Microgateway antes da versão 2.5.2, execute os dois comandos a seguir para fazer upgrade do KVM e da política de autenticação:

upgradekvm -o org -e env -u username

Para mais informações sobre esse comando, consulte Como fazer upgrade do KVM.

O próximo comando faz upgrade do proxy edgemicro-oauth que foi implantado na sua organização da Apigee quando você configurou o Edge Microgateway. Esse proxy fornece os requisitos para serviços necessários para gerar tokens.

upgradeauth -o org -e env -u username

Para mais informações sobre esse comando, consulte Como fazer upgrade do proxy edgemicro-auth.

Rotação das chaves

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 mais informações sobre esse comando, consulte Como alternar chaves.

edgemicro rotatekey -o org -e env -u username -k kid_value

Exemplo:

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v6.9.1
current edgemicro version is 2.5.7
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

O parâmetro -k especifica um ID de chave (kid). Esse ID é usado para corresponder a uma chave específica. O Edge Microgateway usa esse valor para escolher entre um conjunto de chaves durante a rotação de chaves. Para mais informações, consulte a Seção 4.5 da especificação de chave da Web JSON.

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

1. Abra o arquivo de configuração do Edge Micro: ~/.edgemicro/org-env-config.yaml
2. 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.

1. Reinicie o Edge Microgateway no modo de depuração. Para fazer isso, adicione DEBUG=* ao início do comando start. Exemplo:

   DEBUG=* edgemicro start -o  myorg -e test -k
         db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
         6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed

2. Inicie o depurador e configure-o para detectar o número da porta do processo de depuração.
3. 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.

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

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

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

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

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.

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

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

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

1. Verifique se você tem o Edge Microgateway versão 2.5.25 ou mais recente instalado. Caso contrário, execute o seguinte comando para fazer upgrade para a versão mais recente:

   npm install -g edgemicro

   Se precisar de ajuda, consulte Como instalar o Edge Microgateway.

2. Crie um arquivo de configuração com o seguinte nome: $HOME/.edgemicro/org_name-env_name-config.yaml

   Exemplo:

   vi $HOME/.edgemicro/foo-bar-config.yaml

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

4. Exporte a seguinte variável de ambiente com o valor "1":

   export EDGEMICRO_LOCAL=1

5. Execute o seguinte comando start, em que você fornece valores para instanciar o proxy local:

   edgemicro start -o org_name -e environment_name -a local_proxy_name \
     -v local_proxy_version -t target_url -b base_path

   Em que:

   • your_org é o nome da "organização" que você usou no nome do arquivo de configuração.
   • your_environment é 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 /

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

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

1. É 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.
2. Se você implantou o Edge Microgateway na nuvem da Apigee, precisa se conectar à Internet para receber um JWT desse endpoint.
3. Interrompa o Edge Microgateway:

   edgemicro stop

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

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

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

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

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.

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:

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:

1. Verifique se você tem o Edge Microgateway versão 2.5.25 ou mais recente instalado. Caso contrário, execute o seguinte comando para fazer upgrade para a versão mais recente:

   npm install -g edgemicro

   Se precisar de ajuda, consulte Como instalar o Edge Microgateway.

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

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

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

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

8. 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":""
}