Como instalar a integração Send Event to Endpoint através do Marketplace da Azion

Azion Send Event to Endpoint é uma integração serverless disponível no Marketplace da Azion. Essa integração permite transmitir dados de uma requisição para um endpoint HTTP, recolhendo os dados de requisição e os transmitindo para um endpoint definido pelo usuário por meio de uma API Javascript.

A integração também possibilita que você especifique que tipo de dados deseja recolher editando um arquivo JSON.

Após o envio dos dados coletados, a integração permite que a requisição prossiga através do Rules Engine.

Obtenha a integração

Para usar a integração Send Event to Endpoint, siga estes passos:

Acesse o Azion Console > Marketplace.
Na homepage do Marketplace, selecione o card da integração.
Quando a página da integração abrir, clique no botão Install.

Aparecerá uma mensagem indicando que sua integração foi instalada com sucesso.

Configure a integração

Configure um edge firewall

Para iniciar este processo, siga os passos:

Em Products menu, selecione Edge Firewall na seção Secure.
Clique no botão + Edge Firewall.
Dê um nome fácil de lembrar ao seu edge firewall.
Habilite o switch para Edge Functions.
Clique no botão Save

Pronto. Você instanciou o edge firewall para sua função.

Instancie a integração

Para instanciar a integração Send Event to Endpoint, enquanto ainda estiver na página do Edge Firewall:

Selecione a aba Functions Instances e siga estas passos:
Clique no botão + Function Instance.
Dê um nome fácil de lembrar à sua instância.
No menu suspenso, selecione a função Send Event to Endpoint.

Esta ação irá carregar a aba Arguments.

O formulário JSON dos Arguments para esta integração ficará assim:

{
  "metadata": ["remote_addr"],
  "headers": ["x-hello"],
  "body": ["message", "user.id"],
  "http_connection_args": {
  "endpoint": "http://example_api:3000/test",
  "headers": {
    "Authorization": "FakeAuth",
      "X-Provider": "Azion Cells"
  }
  }
}

Onde:

Campo	Obrigatório	Tipo de dado	Notas
`metadata`	Não	Null ou Array	Define quais campos de metadados serão transmitidos. Quando for definido como `null` (ou não for definido), todos os campos de metadados serão transmitidos. Se você não quiser transmitir nenhum metadado, deverá definir uma matriz vazia `[ ]` como o valor desse campo.
`headers`	Não	Null ou Array	Define quais cabeçalhos de requisição serão transmitidos. Quando for definido como `null` (ou não for definido), todos os cabeçalhos de requisição serão transmitidos. Se você não quiser transmitir nenhum cabeçalho, deverá definir uma matriz vazia `[ ]` como o valor desse campo.
`body`	Não	Null ou Array	Define quais campos do `body request` serão transmitidos. Quando for definido como `null` (ou não for definido), todos os campos do corpo da requisição serão transmitidos. Se você não quiser transmitir nenhum campo `body request`, você deverá definir uma matriz vazia `[ ]` como o valor desse campo. Para filtrar campos de vários níveis, use a notação de ponto. Por exemplo, se você usar a string `user.name`, a função procurará o campo “name” dentro do objeto “user” no `body request`.
`connection_args`	Sim	Objeto	Define os dados que serão usados para transmitir os dados da requisição. A URL na qual os dados serão postados é definida pelo endpoint. Os cabeçalhos especificam quais cabeçalhos serão incluídos na requisição de busca. Um cabeçalho adicional `Content-Type: application/json` será usado.
`s3_connection_args`	Não	Objeto	Define os argumentos a serem usados com um bucket S3.
`s3_connection_args.endpoint`	Apenas ao usar `s3_connection_args`	String	Define o endpoint do provedor S3.
`s3_connection_args.bucket`	Apenas ao usar `s3_connection_args`	String	Define o nome do bucket de destino.
`s3_connection_args.region`	Apenas ao usar `s3_connection_args`	String	Define a região do bucket S3.
`s3_connection_args.access_key`	Apenas ao usar `s3_connection_args`	String	Define a chave de acesso usada para conectar-se com o bucket S3.
`s3_connection_args.secret_key`	Apenas ao usar `s3_connection_args`	String	Define uma chave secreta para ser usada na conexão com o bucket S3.
`s3_connection_args.file_path`	Não	String	Define o caminho do arquivo criado para armazenar a função. Valor padrão: `/`
`s3_connection_args.use_date_prefix`	Não	String	Quando habilitado, incluirá uma sub-pasta com a data atual (no formato YYYY-MM-DD) para o caminho do arquivo. Valor padrão: `true`

Esta integração retornará uma resposta com os dados transmitidos em um arquivo JSON com a seguinte aparência:

{
  "body": {
  "field_a": <data>,
  ...
  },
  "geoip_asn": <data>,
  "geoip_city": <data>,
  "geoip_city_continent_code": <data>,
  "geoip_city_country_code": <data>,
  "geoip_city_country_name": <data>,
  "geoip_continent_code": <data>,
  "geoip_country_code": <data>,
  "geoip_country_name": <data>,
  "geoip_region": <data>,
  "geoip_region_name": <data>,
  "headers": {
  "x-header-a": <data>,
  ...
  },
  "remote_addr": <data>,
  "remote_port": <data>,
  "remote_user": <data>,
  "request_id": <data>,
  "request_url": <data>,
  "server_protocol": <data>,
  "ssl_cipher": <data>,
  "ssl_protocol": <data>
}

Observe como os campos request_id, request_url e metadados serão entregues na raiz do arquivo JSON, enquanto os campos body e os cabeçalhos da requisição serão enviados nos objetos.

Você também pode usar um arquivo JSON “catch-all” para as Args, como este:

{
    "connection_args": {
        "endpoint": "http://example_api:3000/test",
    }
}

Saída dos arquivos S3

Para cada nova execução da função, um novo arquivo será gerado no bucket S3 fornecido. O arquivo será nomeado com base no ID da requisição que iniciou a função.

Exemplo: se o parâmetro connection_args.file_path estiver definido como /meus-dados/ e a função for executada em 9 de maio de 2023, com o ID da requisição abcd-1234, o arquivo resultante será salvo em /meus-dados/2023-05-09/abcd-1234.json. Se o parâmetro connection_args.use_date_prefix estiver definido como false, o arquivo resultante será salvo como /meus-dados/abcd-1234.json.

Se não forem fornecidos http_connection_args ou s3_connection_args nos argumentos JSON, a função não terá nenhum argumento de conexão válido para utilizar. A requisição será encerrada e uma mensagem de erro em formato JSON será enviada para indicar a causa do problema.

{
  "error": "A001",
  "detail": "The function instance is missing or has invalid required arguments."
}

Se a função não conseguir se conectar ao endpoint HTTP ou ao provedor S3, a requisição do usuário será ignorada. Independentemente disso, um registro de erro será criado, ao qual o cliente poderá ter acesso por meio do Data Stream.

Por exemplo, se uma chave de acesso inválida for usada, será exibido o seguinte aviso:

[Send event to endpoint] S3 connection error;
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error>
  <Code>InvalidAccessKeyId</Code>
  <Message>The key 'DAKEY' is not valid</Message>
</Error>

Por fim, se você fornecer as opções de conexão corretas tanto para o endpoint HTTP quanto para o bucket S3, a função entregará os dados do evento para ambas as fontes simultaneamente.

Selecione a aba Functions e siga estas passos:
Clique no botão Add⁠ Function.
Dê um nome fácil de lembrar à sua instância.
No menu suspenso, selecione a função Send Event to Endpoint.

Depois de selecionar a integração, um formulário com o código-fonte da integração será carregado. O⁠ código-fonte da integração não pode ser modificado. No mesmo formulário, você tem outra aba: Args. Na aba Args, você passará os parâmetros para configurar sua integração.

O formulário JSON das Args para esta integração ficará assim:

{
  "metadata": ["remote_addr"],
  "headers": ["x-hello"],
  "body": ["message", "user.id"],
  "http_connection_args": {
  "endpoint": "http://example_api:3000/test",
  "headers": {
    "Authorization": "FakeAuth",
      "X-Provider": "Azion Cells"
  }
  }
}

Onde:

Campo	Obrigatório	Tipo de dado	Notas
`metadata`	Não	Null ou Array	Define quais campos de metadados serão transmitidos. Quando for definido como `null` (ou não for definido), todos os campos de metadados serão transmitidos. Se você não quiser transmitir nenhum metadado, deverá definir uma matriz vazia `[ ]` como o valor desse campo.
`headers`	Não	Null ou Array	Define quais cabeçalhos de requisição serão transmitidos. Quando for definido como `null` (ou não for definido), todos os cabeçalhos de requisição serão transmitidos. Se você não quiser transmitir nenhum cabeçalho, deverá definir uma matriz vazia `[ ]` como o valor desse campo.
`body`	Não	Null ou Array	Define quais campos do `body request` serão transmitidos. Quando for definido como `null` (ou não for definido), todos os campos do corpo da requisição serão transmitidos. Se você não quiser transmitir nenhum campo `body request`, você deverá definir uma matriz vazia `[ ]` como o valor desse campo. Para filtrar campos de vários níveis, use a notação de ponto. Por exemplo, se você usar a string `user.name`, a função procurará o campo “name” dentro do objeto “user” no `body request`.
`connection_args`	Sim	Objeto	Define os dados que serão usados para transmitir os dados da requisição. A URL na qual os dados serão postados é definida pelo endpoint. Os cabeçalhos especificam quais cabeçalhos serão incluídos na requisição de busca. Um cabeçalho adicional `Content-Type: application/json` será usado.
`s3_connection_args`	Não	Objeto	Define os argumentos a serem usados com um bucket S3.
`s3_connection_args.full_host`	Apenas ao usar `s3_connection_args`	String	Define o host completo do bucket S3.
`s3_connection_args.region`	Apenas ao usar `s3_connection_args`	String	Define a região do bucket S3.
`s3_connection_args.access_key`	Apenas ao usar `s3_connection_args`	String	Define a chave de acesso usada para conectar-se com o bucket S3.
`s3_connection_args.secret_key`	Apenas ao usar `s3_connection_args`	String	Define uma chave secreta para ser usada na conexão com o bucket S3.
`s3_connection_args.file_path`	Não	String	Define o caminho do arquivo criado para armazenar a função. Valor padrão: `/`
`s3_connection_args.use_date_prefix`	Não	String	Quando habilitado, incluirá uma sub-pasta com a data atual (no formato YYYY-MM-DD) para o caminho do arquivo. Valor padrão: `true`

Esta integração retornará uma resposta com os dados transmitidos em um arquivo JSON com a seguinte aparência:

{
  "body": {
  "field_a": <data>,
  ...
  },
  "geoip_asn": <data>,
  "geoip_city": <data>,
  "geoip_city_continent_code": <data>,
  "geoip_city_country_code": <data>,
  "geoip_city_country_name": <data>,
  "geoip_continent_code": <data>,
  "geoip_country_code": <data>,
  "geoip_country_name": <data>,
  "geoip_region": <data>,
  "geoip_region_name": <data>,
  "headers": {
  "x-header-a": <data>,
  ...
  },
  "remote_addr": <data>,
  "remote_port": <data>,
  "remote_user": <data>,
  "request_id": <data>,
  "request_url": <data>,
  "server_protocol": <data>,
  "ssl_cipher": <data>,
  "ssl_protocol": <data>
}

Observe como os campos request_id, request_url e metadados serão entregues na raiz do arquivo JSON, enquanto os campos body e os cabeçalhos da requisição serão enviados nos objetos.

Você também pode usar um arquivo JSON “catch-all” para as Args, como este:

{
    "connection_args": {
        "endpoint": "http://example_api:3000/test",
    }
}

Saída dos arquivos S3

Para cada nova execução da função, um novo arquivo será gerado no bucket S3 fornecido. O arquivo será nomeado com base no ID da requisição que iniciou a função.

{
  "error": "A001",
  "detail": "The function instance is missing or has invalid required arguments."
}

Por exemplo, se uma chave de acesso inválida for usada, será exibido o seguinte aviso:

[Send event to endpoint] S3 connection error;
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error>
  <Code>InvalidAccessKeyId</Code>
  <Message>The key 'DAKEY' is not valid</Message>
</Error>

Por fim, se você fornecer as opções de conexão corretas tanto para o endpoint HTTP quanto para o bucket S3, a função entregará os dados do evento para ambas as fontes simultaneamente.

Configure o Rules Engine

Para concluir, você precisa configurar o Rules Engine para definir o comportamento e os critérios para executar a integração.

Ainda na página Edge Firewall:

Selecione a aba Rules Engine.
Clique no botão + Rule Engine.
Dê um nome fácil de lembrar à sua nova regra.
Selecione um criteria (critério) para executar a integração.

Exemplo: if Host matches yourdomain.com.

Abaixo, selecione um behavior (comportamento) para os criteria (critérios). Neste caso, será Run Function.
- Selecione a função adequada de acordo com o nome que você deu na etapa de instanciação.
Clique no botão Save.

Agora, no Console, você deve configurar seu domínio para que ele seja protegido pelo seu edge firewall.

No Products menu, selecione Domains.
Clique no domínio que você deseja proteger com sua função Sent Event to Endpoint.
Na seção Settings, clique no seletor de Edge Firewall e escolha o edge firewall que você acabou de criar.
Clique no botão Save.

Pronto. Agora, a integração Send Event to Endpoint está sendo executada para cada requisição feita ao domínio indicado.

Selecione a aba Rules Engine.
Clique no botão New Rule.
Dê um nome fácil de lembrar à sua nova regra.
Selecione um criterio (criteria) para executar a integração. Por exemplo: if Hostname is equal xxxxxxxxxxxx.map.azionedge.net/classes.
Abaixo, selecione um comportamento para os criteria. Neste caso, será Run Function. Em seguida, selecione a função Send Event to Endpoint de acordo com o nome que você deu a ela na etapa instanciada.
Clique no botão Save.

Pronto. Agora, a integração Send Event to Endpoint está sendo executada para cada requisição feita ao domínio indicado.