Agrupamento de solicitações de API com NGINX Plus e o módulo NGINX JavaScript

A versão do módulo NGINX JavaScript lançada com o NGINX Plus R15 agora pode emitir sub-solicitações, o que significa que as solicitações podem ser iniciadas em código JavaScript. Isso permite que um novo conjunto de casos de uso seja abordado.

Um desses casos de uso é o agrupamento de solicitações de API para que uma única solicitação de API de um cliente possa ser transformada em várias solicitações de API para um conjunto de servidores de back-end, e as respostas agregadas em uma única resposta para o cliente. Neste blog, estamos usando um site de comércio eletrônico como exemplo – quando o cliente solicita informações sobre um produto específico, sub-solicitações são feitas para três serviços de back-end: catálogo, inventário e avaliações de clientes.

Esta postagem se baseia no exemplo de sub-solicitação no anúncio do NGINX Plus R15 , que mostra como usar sub-solicitações para enviar a mesma solicitação a dois servidores de back-end e retornar apenas a primeira resposta ao cliente.

[ Editor – Esta postagem é uma das várias que exploram casos de uso para o módulo NGINX JavaScript. Para uma lista completa, consulte Casos de uso para o módulo JavaScript NGINX .

A postagem foi atualizada para usar a diretiva js_import , que substitui a diretiva js_include no NGINX Plus R23 e posteriores. Para obter mais informações, consulte a documentação de referência do módulo NGINX JavaScript – a seção Configuração de exemplo mostra a sintaxe correta para a configuração do NGINX e arquivos JavaScript. ]

INTRODUÇÃO

O objetivo desta postagem é fornecer exemplos práticos de processamento em lote de solicitações de API que sejam simples e diretos. Os exemplos atendem a todos os seguintes requisitos:

• O método HTTP GET é usado para todas as solicitações.
• Todas as respostas estão no formato JSON.

• Dois estilos de solicitações de API são suportados:

  • O argumento para o programa da API é o elemento final do URI. Chamamos isso de estilo de solicitação de elemento final . Em nosso exemplo, uma solicitação de cliente para /batch-api/product/14286 gera solicitações para /myapi/catalog/14286 , /myapi/inventory/14286 e /myapi/review/14286 .
  • O argumento é identificado na string de consulta do URI. Chamamos isso de estilo de solicitação de string de consulta . No exemplo, uma solicitação para /batch-api2/product?item=14286 gera solicitações para /myapi/catalog.php?item=14286 , /myapi/inventory.php?item=14286 e /myapi/review.php?item=14286 .

  Observe que com qualquer estilo pode haver argumentos adicionais na string de consulta.

• O conjunto de sub-solicitações acionadas por uma solicitação do cliente é configurável dinamicamente, o que significa que podemos alterá-lo sem editar manualmente a configuração do NGINX Plus e recarregá-la.
• As solicitações de API para os servidores de backend são independentes umas das outras.

visão geral da solução

Além de usar o novo recurso de sub-solicitação do NGINX JavaScript, esta solução utiliza o recurso de armazenamento de chave-valor do NGINX Plus, permitindo que alterações de configuração sejam feitas dinamicamente com a API do NGINX Plus .

Os gráficos a seguir ilustram os dois estilos de solicitação suportados.

Estilo de solicitação do elemento final:

Estilo de solicitação de sequência de consulta:

Em ambos os exemplos, o cliente precisa obter informações sobre um produto do catálogo, inventário e serviços de avaliação. Ele envia uma solicitação ao NGINX Plus, passando o número do item como parte do URI ou na string de consulta. As solicitações são então enviadas aos três serviços e as respostas são agregadas em uma única resposta ao cliente.

Há dois componentes necessários para que isso funcione com o NGINX Plus: um programa JavaScript e a configuração do NGINX Plus .

O programa JavaScript

A função JavaScript batchAPI() é chamada para cada solicitação do cliente. Ele obtém a lista separada por vírgulas de URIs de API do armazenamento de chave-valor e itera por eles, fazendo uma sub-solicitação para cada um e especificando a função de retorno de chamada done() para processar cada resposta. Para solicitações de estilo de elemento final, o último elemento do URI, armazenado na variável NGINX $uri_suffix , é passado como a string de consulta de cada sub-solicitação, junto com quaisquer outros argumentos de string de consulta no URI do cliente original. Para solicitações de estilo de string de consulta, a string de consulta das solicitações do cliente é passada como a string de consulta de cada sub-solicitação.

As chamadas são feitas na ordem em que são listadas no armazenamento de chave-valor, mas são assíncronas, de modo que as respostas podem retornar em qualquer ordem. As respostas são agregadas em uma única resposta ao cliente na ordem em que são recebidas. Aqui está uma versão mínima do programa JavaScript:

Uma versão do programa JavaScript com tratamento de erros, registro e comentários mais abrangentes está disponível no repositório GitHub Gist como batch-api.js .

Configuração mínima do NGINX Plus

A configuração do NGINX Plus a seguir implementa os dois estilos de solicitação discutidos acima, usando um grupo de servidores upstream. Para manter as coisas simples, esta configuração pressupõe que os servidores upstream são capazes de traduzir uma chamada do formato /myapi/ service / item# (estilo de elemento final) para /myapi/ service .php/?item= item# (estilo de string de consulta), que é o formato URI "nativo" para PHP, a linguagem para nossos serviços de catálogo, inventário e revisão de amostra.

Para uma configuração mais abrangente do NGINX Plus que realiza a tradução em si, consulte Expandindo a configuração do NGINX para traduzir URIs abaixo.

Vamos dar uma olhada no arquivo de configuração seção por seção e explicar o que cada parte faz:

• Importe o arquivo JavaScript :

• Defina um armazenamento de chave-valor para manter a lista de solicitações de API em que o último elemento do URI identifica o argumento para o programa de API. A chave usa a variável $uri_prefix para capturar a parte do URI antes do último / :

  No NGINX Plus R16 e versões posteriores, você pode aproveitar dois recursos adicionais de chave-valor:

  • Defina um tempo de expiração para as entradas em um armazenamento de chave-valor, adicionando o parâmetro timeout à diretiva keyval_zone . Por exemplo, para que cada URI em lote expire diariamente, adicione timeout=1d .
  • Sincronize o armazenamento de chave-valor em um cluster de instâncias do NGINX Plus adicionando o parâmetro sync à diretiva keyval_zone . Você também deve incluir o parâmetro timeout neste caso.

  Para obter instruções sobre como configurar a sincronização para armazenamentos de chave-valor, consulte o Guia de administração do NGINX Plus .

• Defina outro armazenamento de chave-valor para APIs onde o argumento é identificado na sequência de consulta. Aqui, a chave ( $uri ) captura o URI inteiro, sem incluir a string de consulta:

• Defina dois mapas para dividir o URI em duas partes para APIs que aceitam solicitações em que o argumento é o último elemento do URI. A variável $uri_prefix captura os elementos do URI antes do último / e $uri_suffix captura o elemento final:

• Defina o grupo upstream de servidores de API (aqui, eles estão sendo executados no host local junto com o NGINX Plus):

• Defina o servidor virtual que manipula solicitações e subsolicitações do cliente:

• Defina um local para manipular solicitações de clientes que usam o estilo final‑element, que é indicado para a função batchAPI definindo a variável $batch_api_arg_in_uri como on :

• Defina um local para manipular solicitações de clientes que usam o estilo de string de consulta, que é indicado para a função batchAPI definindo a variável $batch_api_arg_in_uri como off :

• Defina o local que manipula as sub-solicitações:

• Habilite a API NGINX Plus para que os dados possam ser mantidos no armazenamento de chave-valor:

Aqui está a configuração completa:

Configurando as solicitações de API em lote

Estamos usando o recurso de armazenamento de chave-valor do NGINX Plus para mapear solicitações de entrada do cliente para um conjunto de solicitações de API a serem executadas. A configuração na seção anterior define armazenamentos de chave-valor separados para os dois estilos de solicitação:

• O armazenamento de chave-valor para o estilo de elemento final é chamado batch_api e a chave é a variável $uri_prefix , que captura os elementos antes do / final do URI da solicitação.
• O armazenamento de chave-valor para o estilo de sequência de consulta é denominado batch_api2 e a chave é a variável $uri , que captura o URI de solicitação completo sem a sequência de consulta.

Em ambos os armazenamentos de chave-valor, o valor associado a cada chave é uma lista separada por vírgulas de URIs que são disponibilizados em tempo de execução nas variáveis $batch_api ou $batch_api2 .

Para solicitações de estilo de elemento final, queremos mapear uma solicitação de cliente para /batch-api/product para solicitações para os três serviços /myapi/catalog , /myapi/inventory e /myapi/review , de modo que uma solicitação para /batch-api/product/14286 resulte em solicitações para /myapi/catalog/14286 , /myapi/product/14286 e /myapi/review/14286 .

Para adicionar esses mapeamentos ao armazenamento de chave-valor batch_api , enviamos a seguinte solicitação para a instância do NGINX Plus em execução na máquina local:

$ curl -iX POST -d '{"/batch-api/product":"/myapi/catalog,/myapi/inventory,/myapi/review"}' http://localhost/api/3/http/keyvals/batch_api

Para as solicitações no estilo de sequência de consulta, queremos mapear uma solicitação de cliente para /batch-api2/product para solicitações aos três serviços /myapi/catalog.php , /myapi/inventory.php e /myapi/review.php , de modo que uma solicitação para /batch-api2/product?item=14286 resulte em solicitações para /myapi/catalog?item=14286 , /myapi/product?item=14286 e /myapi/review?item=14286 .

Para adicionar esses mapeamentos ao armazenamento de chave-valor batch_api2 , enviamos esta solicitação:

$ curl -iX POST -d '{"/batch-api2/product":"/myapi/catalog.php,/myapi/inventory.php,/myapi/review.php"}' http://localhost/api/3/http/keyvals/batch_api2

Executando os Exemplos

As mesmas páginas PHP manipulam solicitações feitas em ambos os estilos de solicitação. Para simplificar, assumimos que os servidores de backend são capazes de traduzir URIs de estilo de elemento final ( /myapi/ service / item# ) em URIs de estilo de string de consulta ( /myapi/service.php?item=item# ) . Não é necessário traduzir URIs no estilo de string de consulta, pois esse é o formato de URI “nativo” para programas PHP.

Todos os serviços retornam uma resposta no formato JSON que inclui o nome do serviço e o argumento do item. Por exemplo, uma solicitação para /myapi/catalog.php?item=14286 resulta na seguinte resposta de catalog.php :

{"service":"Catálogo","item":"14286"}

Embora os programas PHP usados nesses exemplos incluam o nome do serviço na resposta, isso pode não ser o caso para todos os serviços. Para ajudar a corresponder as respostas aos serviços que as geraram, o programa JavaScript inclui o URI na resposta agregada.

Por exemplo, a resposta agregada para uma solicitação de /batch-api/product/14286 é a seguinte (embora a ordem das três respostas dos componentes possa variar):

[["/myapi/review/14286",{"service":"Avaliar","item":"14286"}],["/myapi/inventory/14286",{"service":"Inventário","item":"14286"}],["/myapi/catalog/14286",{"service":"Catálogo","item":"14286"}]]

Expandindo a configuração do NGINX Plus para traduzir URIs

Conforme mencionado, a configuração mínima do NGINX Plus discutida acima pressupõe que os servidores de API sejam capazes de traduzir URIs do formato /myapi/ service / item# para /myapi/ service .php/?item= item# . Também podemos implementar a tradução na configuração do NGINX Plus fazendo as seguintes alterações.

• Adicione um novo grupo upstream para receber as sub-solicitações:

• Adicione um novo servidor virtual para escutar solicitações recebidas pelo grupo upstream de serviços . Quando solicitações no estilo de string de consulta são recebidas, elas são simplesmente enviadas por proxy para o grupo upstream api_servers porque o URI já tem a extensão .php . Quando solicitações de estilo de elemento final são recebidas, o URI é reescrito para que o último elemento no URI seja removido e convertido em um argumento de string de consulta:

• Altere o local /myapi para proxy para o novo grupo upstream:

Aqui está a configuração completa:

Componentes adicionais

Os programas JavaScript de exemplo e as configurações do NGINX Plus podem ser adaptados a outros estilos de APIs, mas se você quiser testar usando todos os componentes usados para criar esta postagem do blog, eles estão disponíveis em nosso repositório Gist no GitHub, incluindo a configuração do NGINX Unit para servir as páginas PHP:

lote-api.js
catálogo.php
inventário.php
revisão.php
unidade.config

Conclusão

Esses exemplos mostram como agrupar solicitações de API e fornecer uma resposta agregada ao cliente. O armazenamento de chave-valor do NGINX Plus nos permite configurar as solicitações de API dinamicamente com a API do NGINX Plus . Os sistemas de API variam bastante em suas operações exatas, portanto, há muitos aprimoramentos que podem ser feitos neste exemplo para atender às necessidades de uma API específica.

Você pode começar a testar sub-solicitações JavaScript do NGINX com o NGINX Open Source , mas se quiser testar os exemplos de agrupamento de APIs ou outros casos de uso que aproveitem os recursos do NGINX Plus, como o armazenamento de chave-valor e a API do NGINX Plus , solicite um teste gratuito de 30 dias e comece a experimentar.