Enviar eventos de gatilho para o AWS EventBridge
Nesta página
- Procedimento
- Configurar a origem do evento do parceiro MongoDB
- Configurar o gatilho
- Associar a origem de eventos de gatilho a um barramento de eventos
- Tratamento personalizado de erros
- Crie um novo manipulador de erros personalizado
- Parâmetros do manipulador de erros
- Códigos de erro
- Registros do manipulador de erros
- Exemplo de evento
- Otimização de desempenho
O MongoDB oferece um AWS Eventbridge fonte de evento de um parceiro que permite enviar eventos do Atlas Triggers para um barramento de evento em vez de chamar uma função do Atlas . Você pode configurar qualquer tipo de Trigger para enviar eventos para o EventBridge. Os gatilhos de banco de dados também oferecem suporte ao tratamento personalizado de erros, para reduzir as suspensões do gatilho devido a erros não críticos.
Você só precisa enviar trigger eventos de para o EventBridge é um Amazon Web Services IDde conta . Este guia orienta você na localização do ID da sua conta , na configuração do trigger, na associação da origem do evento de trigger a um barramento de evento e na configuração do tratamento de erros personalizado.
Observação
Guia oficial de origem de eventos de parceiros da AWS
Este guia é baseado em Receber eventos da Amazon de um parceiro SaaS documentação.
Procedimento
Observação
As entradas individuais para um evento de trigger do EventBridge devem ser menores que 256 KB.
Saiba como reduzir o tamanho da entrada do PutEvents
na seção Otimização de desempenho .
Configurar a origem do evento do parceiro MongoDB
Para enviar eventos de trigger para o AWS EventBridge, você precisa do AWS account ID da conta que deve receber os eventos.
Abra o Console do Amazon EventBridge e clique Partner event sources em no menu de navegação.
Procure a origem do evento do parceiro MongoDB e clique em Set up.
Na MongoDB página de origem do evento de parceiro, clique Copy Amazon Web Services ID em para copiar o da sua conta para a área de transferência.
Configurar o gatilho
Depois AWS account ID de ter o, você pode configurar um gatilho trigger de banco trigger de dados ou um para enviar eventos para o EventBridge.
Você pode configurar o trigger na UI do Atlas ou usando a App Services CLI.
Na UI do Atlas , crie e configure um novo gatilho de banco de dados (trigger ) ou scheduled trigger (trigger agendado) com as seguintes configurações:
Selecione EventBridge como o tipo de evento .
Cole o AWS Account ID que você copiou do EventBridge.
Selecione um AWS Region para o qual enviar os eventos de trigger.
Observação
Regiões AWS suportadas
Para obter uma lista completa das regiões da AWS compatíveis, consulte o guia de Recebimento de eventos de um parceiro Saas da Amazon.
(Opcional apenas para gatilhos de banco de dados) Configure uma função para lidar com erros de trigger .
Para obter mais detalhes, consulte a seção Tratamento de erros personalizado nesta página.
clique para ampliarPara habilitar o JSON estendido, alterne a configuração Enable Extended JSON na seção Advanced (Optional) .
Por padrão, triggers convertem os tipos BSON em objetos de evento em tipos JSON padrão.
A ativação do Extended JSON preserva as informações do tipo BSON ao serializar os objetos de evento no formato Extended JSON . Isso preserva informações de tipo às custas de legibilidade e interoperabilidade.
Autenticar um usuário do MongoDB Atlas
Use sua chave de API de administração do MongoDB Atlas para fazer login na App Services CLI:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>" Extraia os arquivos de configuração mais recentes do seu aplicativo
Execute o seguinte comando para obter uma cópia local dos seus arquivos de configuração:
appservices pull --remote=<App ID> Por padrão, o comando extrai arquivos para o diretório de trabalho atual. Você pode especificar um caminho de diretório com a bandeira
--local
opcional.Crie um arquivo de configuração de trigger em seu diretório
/triggers
local. Omita o campofunction_name
e defina um processador de eventoAWS_EVENTBRIDGE
.Defina o campo
account_id
como AWS Account ID que você copiou do EventBridge.Defina o campo
region
como uma região Amazon Web Services .Observação
Regiões AWS suportadas
Para obter uma lista completa das regiões da AWS compatíveis, consulte o guia de Recebimento de eventos de um parceiro Saas da Amazon.
Para habilitar o JSON estendido, defina o campo
extended_json_enabled
comotrue
.Por padrão, triggers convertem os tipos BSON em objetos de evento em tipos JSON padrão.
A ativação do Extended JSON preserva as informações do tipo BSON ao serializar os objetos de evento no formato Extended JSON . Isso preserva informações de tipo às custas de legibilidade e interoperabilidade.
(Opcional apenas para gatilhos de banco de dados) Configure uma função para lidar com erros de trigger .
Para obter mais detalhes, consulte a seção Tratamento de erros personalizado nesta página.
O arquivo de configuração do trigger deve ser semelhante ao seguinte:
{ "name": "...", "type": "...", "event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "<AWS Account ID>", "region": "<AWS Region>", "extended_json_enabled": <boolean> } } } }
Associar a origem de eventos de gatilho a um barramento de eventos
Retorne ao console do EventBridge.
Selecione Fontes de evento de parceiros no painel de navegação.
Na tabela Partner event sources, localize e selecione a fonte de trigger Pending e, em seguida, clique em Associate with event bus.
Na tela Associate with event bus , defina quaisquer permissões de acesso necessárias para outras contas e organizações e clique em Associate.
Depois que a associação é confirmada, o status da origem do evento de trigger muda de Pending para Active e o nome do barramento do evento é atualizado para corresponder ao nome da origem do evento . Agora você pode criar regras que trigger eventos a partir dessa origem de evento de parceiro.
Para obter mais informações,consulte Criação de uma regra que é acionada em um evento de parceiro SaaS .
Tratamento personalizado de erros
Observação
Somente Database Tools suportam manipuladores de erros personalizados
Atualmente, apenas os gatilhos de banco de dados (trigger) oferecem suporte ao tratamento personalizado de erros. Os gatilhos de autenticação e os gatilhos agendados não permitem o tratamento de erros personalizado no momento.
Você pode criar um manipulador de erro para executar em uma falha de trigger quando a nova tentativa não for bem-sucedida. O tratamento personalizado de erros permite determinar se um erro do AWS Eventbridge é crítico o suficiente para suspender o trigger ou se é aceitável ignorar o erro e continuar processando outros eventos.
Para obter mais informações sobre os gatilhos de banco de dados suspensos, consulte Triggers suspensos.
Crie um novo manipulador de erros personalizado
Você pode criar um novo manipulador de erros na UI do Atlas , usando a App Services CLI ou por meio da App Services Admin API.
Este procedimento mostra como criar a nova função diretamente na página Create a Trigger .
Você também pode criar a função a partir da página Functions . Para mais informações sobre como definir Funções no Atlas, consulte Definir uma Função.
Escrever o código da função
Na seção Function, escreva o código JavaScript diretamente no editor de funções. O editor de funções contém uma função padrão que você pode editar conforme o necessário. Para obter mais informações sobre a criação de funções, consulte a documentação Funções.
Testar a função
Na aba Testing Console abaixo do editor de funções, você pode testar a função passando valores de exemplo para os parâmetros error
e changeEvent
, conforme mostrado nos comentários do console de teste.
Para obter mais informações sobre esses parâmetros, consulte a seção Parâmetros do manipulador de erros nesta página.
Clique em Run para executar o teste.
Você pode atualizar a configuração do trigger com um manipulador de erro usando a App Services CLI. Para obter mais informações, consulte o procedimento Atualizar um aplicativo .
Autenticar um usuário do MongoDB Atlas
Use sua chave de API de administração do MongoDB Atlas para fazer login na App Services CLI:
appservices login --api-key="<API KEY>" --private-api-key="<PRIVATE KEY>"
Extraia os arquivos de configuração mais recentes do seu aplicativo
Execute o seguinte comando para obter uma cópia local dos seus arquivos de configuração:
appservices pull --remote=<App ID>
Por padrão, o comando extrai arquivos para o diretório de trabalho atual. Você pode especificar um caminho de diretório com a bandeira --local
opcional.
Grave o manipulador de erros
Siga as etapas em Definir uma função para escrever o código-fonte e o arquivo de configuração do manipulador de erros.
Consulte o seguinte manipulador de erros de modelo como exemplo:
exports = async function(error, changeEvent) { // This sample function will log additional details if the error is not // a DOCUMENT_TOO_LARGE error if (error.code === 'DOCUMENT_TOO_LARGE') { console.log('Document too large error'); // Comment out the line below in order to skip this event and not suspend the Trigger throw new Error('Encountered error: ${error.code}'); } console.log('Error sending event to EventBridge'); console.log('DB: ${changeEvent.ns.db}'); console.log('Collection: ${changeEvent.ns.coll}'); console.log('Operation type: ${changeEvent.operationType}'); // Throw an error in your Function to suspend the Trigger // and stop processing additional events throw new Error('Encountered error: ${error.message}'); };
Para mais informações sobre como criar funções, consulte Funções.
Adicione o manipulador de erros à sua configuração de trigger
Adicione um atributo error_handler
ao seu arquivo de configuração de trigger na pasta Triggers
.
O arquivo de configuração do trigger deve ser semelhante ao seguinte:
{ "name": "...", "type": "DATABASE", "event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "<AWS Account ID>", "region": "<AWS Region>", "extended_json_enabled": <boolean> } } }, "error_handler": { "config": { "enabled": <boolean>, "function_name": "<Error Handler Function Name>" } } }
Para obter mais informações, consulte Arquivos de configuração do trigger.
Implemente suas alterações
Execute o seguinte comando para implementar suas alterações:
appservices push
Observação
Esse procedimento refere-se aos endpoints da App Services Admin API . Ele não usa endpoints da API de administração do Atlas .
Autenticar um usuário do MongoDB Atlas
Ligue para o endpoint de login com seu par de chaves da API de administração do MongoDB Atlas :
curl -X POST \ https://services.cloud.mongodb.com/api/admin/v3.0/auth/providers/mongodb-cloud/login \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -d '{ "username": "<Public API Key>", "apiKey": "<Private API Key>" }'
Se a autenticação for bem-sucedida, o corpo da resposta conterá um objeto JSON com um valor access_token
:
{ "access_token": "<access_token>", "refresh_token": "<refresh_token>", "user_id": "<user_id>", "device_id": "<device_id>" }
O access_token
concede acesso à App Services Admin API. Você deve incluí-lo como um token do portador no cabeçalho Authorization
para todas as solicitações da App Services Admin API .
(Opcional) Criar um esquema de implantação
Um rascunho representa um grupo de alterações para aplicação que você pode distribuir ou descartar como uma única unidade. Se você não criar um rascunho, as atualizações serão implementadas automaticamente de forma individual.
Para criar um rascunho, envie uma solicitação POST
sem corpo para o endpoint Create a Deployment Draft (criar um rascunho de implantação):
curl -X POST 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <access_token>'
Crie a função do manipulador de erros
Crie a função para lidar com erros de AWS Eventbridge trigger um com falha por meio de uma POST
solicitação de para o endpoint Criar uma nova função .
curl -X POST \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/functions \ -H 'Authorization: Bearer <access_token>' \ -d '{ "name": "string", "private": true, "source": "string", "run_as_system": true }'
Crie o trigger do AWS EventBridge
Crie o trigger do AWS EventBridge com o tratamento de erros habilitado por meio de uma solicitação POST
para o endpoint Create a Trigger (criar um trigger).
curl -X POST \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/triggers \ -H 'Authorization: Bearer <access_token>' \ -d '{ "name": "string", "type": "DATABASE", "config": { "service_id": "string", "database": "string", "collection": "string", "operation_types": { "string" }, "match": , "full_document": false, "full_document_before_change": false, "unordered": true }, "event_processors": { "AWS_EVENTBRIDGE": { "account_id": "string", "region": "string", "extended_json_enabled": false }, }, "error_handler": { "enabled": true, "function_id": "string" } }'
Implemente suas alterações
Se você criou um rascunho, poderá implantar todas as alterações no rascunho enviando uma solicitação de POST
sem corpo para o endpoint Implantar um rascunho de implantação .
Se você não criou um rascunho como uma primeira etapa, a função individual e as solicitações de trigger são implementadas automaticamente.
curl -X POST \ 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/drafts/{draftId}/deployment' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access_token>' \
Parâmetros do manipulador de erros
O manipulador de erros padrão tem dois parâmetros: error
e changeEvent
.
error
Tem os dois atributos a seguir:
code
: o código da solicitação de colocação do EventBridge com erro. Para obter uma lista de códigos de erro usados pelo manipulador de erros, consulte a seção Códigos de erro nesta página.message
: a mensagem de erro não filtrada de uma solicitação de colocação do EventBridge com erro.
changeEvent
A alteração solicitada em seus dados feita pelo EventBridge. Para obter mais informações sobre os tipos de eventos de alteração e suas configurações, consulte Alterar tipos de eventos.
Códigos de erro
Se um erro foi recebido do EventBridge, o processador de evento analisará o erro como DOCUMENT_TOO_LARGE
ou OTHER
. Esse erro analisado é passado para a função do manipulador de erros por meio do parâmetro error
.
DOCUMENT_TOO_LARGE
Se a entrada de um evento de trigger do EventBridge for maior que 256 KB, o EventBridge lançará um erro. O erro conterá:
código de status: 400 e
total size of the entries in the request is over the limit
.código de status: 413, o que indica uma carga útil muito grande.
Para obter mais informações sobre como reduzir o tamanho da entrada, consulte Otimização de desempenho.
OTHER
O bucket padrão para todos os outros erros.
Dica
Otimizar o tratamento de erros para erros com outro código
Você pode criar casos especiais de tratamento de erros para as mensagens de erro mais comuns, a fim de otimizar o tratamento de erros para erros com um código OTHER
. Para determinar quais erros precisam de casos especiais, recomendamos acompanhar as mensagens de erro mais comuns que você recebe em error.message
.
Registros do manipulador de erros
Você pode visualizar os registros do manipulador de erros do trigger para seu manipulador de erros do trigger do EventBridge nos registros do aplicativo.
Na página Triggers
da UI do Atlas , selecione a aba Logs .
Todos os registros são exibidos por padrão. Para ver somente os registros do manipulador de erros, clique no botão Show errors only .
Passe o valor trigger_error_handler
para o sinalizador --type
para visualizar todos os registros do manipulador de erros.
appservices logs list --type=trigger_error_handler
Observação
Esse procedimento refere-se aos endpoints da App Services Admin API . Ele não usa endpoints da API de administração do Atlas .
Recupere registros do tipo TRIGGER_ERROR_HANDLER
por meio de uma solicitação GET
para o endpoint Retrieve App Services Logs :
curl -X GET 'https://services.cloud.mongodb.com/api/admin/v3.0/groups/{groupId}/apps/{appId}/logs' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <access_token>' -d '{ "type": "TRIGGER_ERROR_HANDLER" }'
Para saber mais sobre como visualizar registros de aplicação , consulte Visualizar registros de aplicativos.
Exemplo de evento
O objeto abaixo configura um trigger para enviar eventos para o AWS Eventbridge e lidar com erros:
"event_processors": { "AWS_EVENTBRIDGE": { "config": { "account_id": "012345678901", "region": "us-east-1" } } }, "error_handler": { "config": { "enabled": true, "function_name": "myErrorHandler.js" } }
Otimização de desempenho
As entradas individuais para um evento de trigger do EventBridge devem ser menores que 256 KB.
Para obter mais informações, consulte a Amazon Web Services Documentação do para calcular o Amazon tamanho da entrada do evento PutEvents. Ao usar gatilhos de banco de dados, a expressão do projeto pode incluir apenas campos especificados, reduzindo o tamanho do documento antes de enviar mensagens para o EventBridge. Para obter mais detalhes sobre a expressão do projeto, consulte a documentação sobre a expressão do projeto no trigger de banco de dados.