Eventos do Amazon Cognito

Se você for novo com o Amazon Cognito Sync, use o AWS AppSync. Como o Amazon Cognito Sync, o AWS AppSync é um serviço para sincronizar dados de aplicações entre dispositivos.

Ele permite que dados do usuário, como preferências de aplicações ou estado de jogos, sejam sincronizados. Ele também amplia essas capacidades ao permitir que vários usuários sincronizem e colaborem em tempo real com dados compartilhados.

Os eventos do Amazon Cognito permitem que você execute uma função do AWS Lambda em resposta a eventos importantes do Amazon Cognito. O Amazon Cognito gera o evento Sync Trigger quando um conjunto de dados é sincronizado. Você pode usar o evento Sync Trigger para executar uma ação quando um usuário atualizar dados. A função pode avaliar e, opcionalmente, manipular os dados antes de serem armazenados na nuvem e sincronizados nos outros dispositivos do usuário. Isso será útil para validar os dados provenientes do dispositivo antes que eles sejam sincronizados com outros dispositivos do usuário ou para atualizar outros valores no conjunto de dados com base nos dados de entrada, como emitir um prêmio quando um jogador atinge um novo nível.

As etapas a seguir orientarão você durante a configuração de uma função Lambda executada toda vez que um conjunto de dados do Amazon Cognito for sincronizado.

nota

Ao usar eventos do Amazon Cognito, você só pode utilizar as credenciais obtidas no Amazon Cognito Identity. Se você tiver uma função Lambda associada, mas chamar UpdateRecords com as credenciais da conta da AWS (credenciais do desenvolvedor), a função Lambda não será invocada.

Como criar uma função no AWS Lambda

Para integrar o Lambda ao Amazon Cognito, primeiro é necessário criar uma função no Lambda. Para fazer isso:

Selecionar a função Lambda no Amazon Cognito

1. Abra o console do lambda.

2. Clique em Create a Lambda function (Criar uma função Lambda).

3. Na tela Select blueprint, procure e selecione "cognito-sync-trigger".

4. Na tela Configure event sources, deixe Event source type definido como "Cognito Sync Trigger" e selecione o grupo de identidades. Clique em Next.

   nota

   Ao configurar um acionador do Amazon Cognito Sync fora do console, você deve adicionar permissões baseadas em recursos do Lambda para permitir que o Amazon Cognito invoque a função. É possível adicionar essa permissão no console do Lambda (consulte Uso de políticas baseadas em recursos para o AWS Lambda) ou usando a operação AddPermission do Lambda.

   Exemplo de política baseada em recursos do Lambda

   A seguinte política baseada em recursos do AWS Lambda concede ao Amazon Cognito uma capacidade limitada de invocar uma função Lambda. O Amazon Cognito só pode invocar a função em nome do grupo de identidades na condição aws:SourceArn e da conta na condição aws:SourceAccount.

   {
       "Version": "2012-10-17",
       "Id": "default",
       "Statement": [
           {
               "Sid": "lambda-allow-cognito-my-function",
               "Effect": "Allow",
               "Principal": {
                   "Service": "cognito-sync.amazonaws.com"
               },
               "Action": "lambda:InvokeFunction",
               "Resource": "<your Lambda function ARN>",
               "Condition": {
                   "StringEquals": {
                       "AWS:SourceAccount": "<your account number>"
                   },
                   "ArnLike": {
                       "AWS:SourceArn": "<your identity pool ARN>"
                   }
               }
           }
       ]
   }

5. Na tela Configure function, insira um nome e uma descrição para a função. Deixe Runtime definido como "Node.js". Deixe o código inalterado no nosso exemplo. O exemplo padrão não faz as alterações nos dados que estão sendo sincronizados. Ele só registra o fato de que o evento Sync Trigger do Amazon Cognito ocorreu. Deixe Handler name definido como "index.handler". Em Role (Função), selecione uma função do IAM que conceda permissão de código para acessar o AWS Lambda. Para modificar funções, consulte o console do IAM. Deixe a opção Advanced settings inalterada. Clique em Next.

6. Na tela Review, revise os detalhes e clique em Create function. A próxima página exibe a nova função Lambda.

Agora que você tem uma função apropriada gravada no Lambda, precisa escolher essa função como handler do evento Sync Trigger do Amazon Cognito. As etapas a seguir percorrerão esse processo.

Na página inicial do console:

1. Clique no nome do grupo de identidades para o qual você deseja configurar os eventos do Amazon Cognito. A página Dashboard (Painel) do grupo de identidades será exibida.

2. No canto superior direito da página Dashboard, clique em Manage Federated Identities. A página Manage Federated Identities (Gerenciar identidades federadas) é exibida.

3. Role a tela para baixo e clique em Cognito Events para expandi-lo.

4. No menu suspenso Sync Trigger, selecione a função Lambda que você quer acionar quando ocorre um evento Sync.

5. Clique em Salvar alterações

Agora, a função Lambda será executada todas as vezes que um conjunto de dados for sincronizado. A próxima seção abordará como ler e modificar os dados na função enquanto eles estão sendo sincronizados.

Como criar uma função Lambda para acionadores de sincronização

Os acionadores de sincronização seguem o padrão de programação que as interfaces do provedor de serviços usam. O Amazon Cognito fornece a entrada na função do Lambda no formato JSON a seguir.

{
  "version": 2,
  "eventType": "SyncTrigger",
  "region": "us-east-1",
  "identityPoolId": "identityPoolId",
  "identityId": "identityId",
  "datasetName": "datasetName",
  "datasetRecords": {
    "SampleKey1": {
      "oldValue": "oldValue1",
      "newValue": "newValue1",
      "op": "replace"
    },
    "SampleKey2": {
      "oldValue": "oldValue2",
      "newValue": "newValue2",
      "op": "replace"
    },..
  }
}

O Amazon Cognito espera o valor de retorno da função no mesmo formato da entrada.

Ao gravar funções para o evento Sync Trigger, observe o seguinte:

• Quando o Amazon Cognito chamar sua função do Lambda durante UpdateRecords, ela deverá responder em até cinco segundos. Se isso não ocorrer, o serviço Amazon Cognito Sync lançará uma exceção LambdaSocketTimeoutException. Você não pode aumentar esse valor de tempo limite.

• Se você receber uma exceção LambdaThrottledException, tente a operação de sincronização novamente para atualizar os registros.

• O Amazon Cognito fornece todos os registros presentes no conjunto de dados como entrada para a função.

• Os registros que o usuário da aplicação atualiza têm o campo op definido como replace. Os registros excluídos têm o campo op definido como remove.

• Você poderá modificar qualquer registro, mesmo se o usuário da aplicação não o atualizar.

• Todos os campos, exceto datasetRecords, são somente leitura. Não os altere. Se você alterar esses campos, não poderá atualizar os registros.

• Para modificar o valor de um registro, atualize o valor e defina op como replace.

• Para remover um registro, defina op como remove ou defina o valor como null.

• Para adicionar um registro, adicione um novo registro à matriz datasetRecords.

• O Amazon Cognito ignora qualquer registro omitido na resposta quando o Amazon Cognito o atualiza.

Amostra de função Lambda

O exemplo de função do Lambda a seguir mostra como acessar, modificar e remover os dados.

console.log('Loading function');

exports.handler = function(event, context) {
    console.log(JSON.stringify(event, null, 2));

    //Check for the event type
    if (event.eventType === 'SyncTrigger') {

        //Modify value for a key
        if('SampleKey1' in event.datasetRecords){
            event.datasetRecords.SampleKey1.newValue = 'ModifyValue1';
            event.datasetRecords.SampleKey1.op = 'replace';
        }

        //Remove a key
        if('SampleKey2' in event.datasetRecords){
            event.datasetRecords.SampleKey2.op = 'remove';
        }

        //Add a key
        if(!('SampleKey3' in event.datasetRecords)){
            event.datasetRecords.SampleKey3={'newValue':'ModifyValue3', 'op' : 'replace'};
        }

    }
    context.done(null, event);
};