`$externalFunction`

Definição

$externalFunction

A fase $externalFunction aciona processos em um recurso específico do AWS Lambda. Sua solicitação para o processo do AWS Lambda pode ser síncrona ou assíncrona.

Crie um AWS Lambda e autentique com o AWS Access Unificado

Para chamar um recurso do AWS Lambda a partir do pipeline do Atlas Stream Processing, seu AWS Lambda deve ser implantado na mesma região da AWS em que seu Atlas Stream Processing está implantado. Para saber mais sobre a implantação de um recurso do AWS Lambda, consulte a documentação da AWS.

Crie uma função de Lambda do Amazon Web Services.

Com a AWS CLI ou pela interface do usuário da AWS, crie uma função lambda.

Observação

Os recursos do AWS Lambda devem ser criados com um tipo de autenticação AWS_IAM, que exige que você crie uma função e uma políticado AWS IAM.
Apenas o tipo de resposta em buffer, e não o de streaming, é compatível.

Configure o acesso unificado do AWS.

Observação

O procedimento descrito aqui cobre apenas o fluxo básico de configurar na IU do Atlas. Para aprender mais, consulte a documentação Configurar o Acesso Unificado da AWS.

Acesso necessário

Para configurar o acesso unificado AWS, você deve ter o acesso Organization Owner ou Project Owner ao projeto.

Pré-requisitos

Observação

Sua política do AWS IAM deve incluir a ação lambda:InvokeFunction.
Substitua os valores de ExternalId e Resource de espaço reservado pelos seus, que estão disponíveis por meio do processo de configuração do Unified AWS Access. Observe que o ExternalId neste exemplo inclui um curinga, correspondente a qualquer função do Lambda com um nome que começa com function-.

Adicionar relações de confiança a uma função existente na IU do Atlas

permission-policy.json

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction"
            ],
            "Resource": "arn:aws:lambda:us-east-1:257394458927:function:<function-name>"
        }
    ]
}

Navegue até a página de integração AWS IAM em seu projeto Atlas e clique no botão Authorize an AWS IAM role.
Crie uma nova função (ou modifique uma função existente) com o role-trust-policy.json mostrado no modal.
Assim que a função for criada (ou a função existente for atualizada com a nova política de confiança), cole o ARN da função no modal.
No console da AWS, acesse IAM > Roles e selecione sua função.
Na aba permissions, adicione uma nova "permissão em linha" para permitir que esta função invoque seu(s) lambda(s). O exemplo permission-policy.json fornecido acima adiciona a permissão para executar qualquer lambda com o nome <function-name>.
Por fim, acesse sua instância de Atlas Stream Processing, adicione um novo AWS Lambda connection e selecione o AWS IAM Role ARN que você configurou na etapa anterior.

Conecte sua instância Atlas Stream Processing à sua função AWS Lambda

Para enviar uma solicitação ao recurso AWS Lambda de dentro do pipeline do Atlas Stream Processing, você deve primeiro adicionar o recurso AWS Lambda como uma conexão no recurso Atlas Stream Processing.

Você pode adicionar seu recurso do AWS Lambda como uma conexão por meio do Atlas UI, do MongoDB Terraform provider, do Atlas CLI ou da Atlas API, conforme mostrado no exemplo a seguir. Você pode atualizar o espaço roleArn reservado no exemplo com o arn de sua configuração do AWS IAM.

curl --user "username:password" --digest \
   --header "Content-Type: application/json" \
   --header "Accept: application/vnd.atlas.2023-02-01+json" \
   --include \
   --data '{"name": "TestAWSLambdaConnection","type": "AWSLambda","aws": {"roleArn": "arn:aws:iam::<aws_account>:role/<role_name>"}}' \
   --request POST "https://cloud.mongodb.com/api/atlas/v2/groups/<group_id>/streams/<tenant_name>/connections"

Sintaxe

Solicitação mínima

O exemplo a seguir mostra os campos obrigatórios para uma solicitação mínima.

{ $externalFunction: {
  connectionName: "myLambdaConnection",
  functionName: "arn:aws:lambda:region:account-id:function:function-name",
  as: "response",
}}

Solicitação customizada

O exemplo personalizado a seguir especifica o tratamento de erros, a execução síncrona e um documento pré-processado do Atlas Stream Processing como carga útil, além dos campos obrigatórios ilustrados acima.

{ $externalFunction: {
        connectionName: "myLambdaConnection",
        functionName: "arn:aws:lambda:region:account-id:function:function-name",
        execution: "sync"
        as: "response",
        onError: "fail",
        payload: [{$replaceRoot: { newRoot: "$fullDocument.payloadToSend" } }, { $addFields: { sum: { $sum: "$randomArray" }}}, { $project: { success: 1, sum: 1 }}],
}}

Observação

O campo onError define o comportamento para erros de nível da API em solicitações síncronas e assíncronas para seu recurso AWS Lambda, assim como para erros de função do AWS Lambda em solicitações síncronas.

O estágio $externalFunction recebe um documento com os seguintes campos:

Campo	Tipo	necessidade	Descrição
`connectionName`	string	Obrigatório	Rótulo que identifica a conexão no registro de conexões, para o qual a solicitação é enviada.
`functionName`	string	Obrigatório	O ARN completo da AWS ou o nome da função AWS Lambda a ser acionada.
`execution`	enum	Opcional	Parâmetro que especifica se a função do Amazon Web Services Lambda deve ser chamada de forma síncrona ou assíncrona. Os valores aceitos são: `sync` `async` O padrão é `sync`, que é necessário se os estágios restantes no pipeline do Atlas Stream Processing exigirem a saída da função do AWS Lambda.
`as`	string	Opcional	Nome do campo para a resposta da REST API. Se o ponto de extremidade retornar 0 bytes, o operador não configurará o campo `as`.
`onError`	string	Opcional	Comportamento quando o operador encontra uma falha relacionada a `HTTPS Status Code` ou ao tempo de execução do Lambda. Deve ser um dos seguintes valores: `"dlq"` : Passe o documento afetado para a fila de mensagens não entregues (DLQ). `"ignore"` : Não faça nada com o documento afetado. `"fail"` : Finalizar o processador de fluxo em caso de erro. `onError` não é acionado por erros decorrentes da configuração incorreta do operador `$externalFunction` em si, como expressões inválidas. Padrão é `"dlq"`.
`payload`	array	Opcional	Pipeline interno personalizado que permite personalizar o corpo da solicitação enviado ao ponto de extremidade da API. `payload` suporta as seguintes expressões: `$project` `$addFields` `$replaceRoot` `$set`

Voltar

$merge

$sessionWindow