Dados em tempo real de

O AWS AppSync permite que você utilize assinaturas para implementar atualizações de aplicativos ao vivo, notificações push etc. Quando os clientes invocam as operações de assinatura do GraphQL, uma conexão segura do WebSocket é automaticamente estabelecida e mantida pelo AWS AppSync. Os aplicativos podem então distribuir dados em tempo real de uma fonte de dados para os assinantes, enquanto o AWS AppSync gerencia continuamente os requisitos de conexão e escalonamento do aplicativo. As seções a seguir mostrarão como funcionam as assinaturas no AWS AppSync.

Diretivas de assinatura do esquema do GraphQL

As assinaturas no AWS AppSync são invocadas como resposta a uma mutação. Isso significa que você pode tornar qualquer fonte de dados no AWS AppSync como tempo real ao especificar uma diretiva do esquema do GraphQL em uma mutação.

As bibliotecas de cliente do AWS Amplify processam automaticamente o gerenciamento de conexões por assinatura. As bibliotecas usam pure WebSockets como protocolo de rede entre o cliente e o serviço.

nota

Para controlar a autorização no momento da conexão para uma assinatura, você pode usar o AWS Identity and Access Management (IAM), o AWS Lambda, o banco de identidades do Amazon Cognito ou os grupos de usuários do Amazon Cognito para autorização no nível do campo. Para obter controles de acesso refinados para assinaturas, anexe resolvedores aos campos de assinatura e execute a lógica usando a identidade do chamador e fontes de dados do AWS AppSync. Para obter mais informações, consulte Autorização e autenticação.

As assinaturas são acionadas a partir de mutações e o conjunto de seleção da mutação é enviado aos assinantes.

O exemplo a seguir mostra como trabalhar com assinaturas do GraphQL. Ele não especifica uma fonte de dados porque a fonte de dados pode ser Lambda, Amazon DynamoDB ou Amazon OpenSearch Service.

Para começar a usar assinaturas, é necessário adicionar um ponto de entrada de assinatura ao esquema, da seguinte forma:

schema {
    query: Query
    mutation: Mutation
    subscription: Subscription
}

Digamos que você tenha um site de postagens de blog e deseje assinar novos blogs e alterações aos blogs existentes. Para fazer isso, adicione a seguinte definição Subscription ao esquema:

type Subscription {
    addedPost: Post
    updatedPost: Post
    deletedPost: Post
}

Digamos também que possui as seguintes mutações:

type Mutation {
    addPost(id: ID! author: String! title: String content: String url: String): Post!
    updatePost(id: ID! author: String! title: String content: String url: String ups: Int! downs: Int! expectedVersion: Int!): Post!
    deletePost(id: ID!): Post!
}

Você pode tornar esses campos em tempo real ao adicionar uma diretiva @aws_subscribe(mutations: ["mutation_field_1", "mutation_field_2"]) para cada uma das assinaturas sobre as quais deseja receber notificações, da seguinte forma:

type Subscription {
    addedPost: Post
    @aws_subscribe(mutations: ["addPost"])
    updatedPost: Post
    @aws_subscribe(mutations: ["updatePost"])
    deletedPost: Post
    @aws_subscribe(mutations: ["deletePost"])
}

Como a @aws_subscribe(mutations: ["",..,""]) recebe uma matriz de entradas de mutação, você pode especificar diversas mutações, que iniciam uma assinatura. Se estiver assinando a partir de um cliente, a consulta do GraphQL poderá ser semelhante ao seguinte:

subscription NewPostSub {
    addedPost {
        __typename
        version
        title
        content
        author
        url
    }
}

A consulta de assinatura é necessária para conexões de cliente e ferramentas.

Com o cliente de pure WebSockets, a filtragem do conjunto de seleção será feita por cliente, pois cada cliente poderá definir seu próprio conjunto de seleção. Nesse caso, o conjunto de seleção da assinatura deve ser um subconjunto do conjunto de seleção da mutação. Por exemplo, uma assinatura addedPost{author title} vinculada à mutação addPost(...){id author title url version} recebe somente o autor e o título da postagem. Ela não recebe os outros campos. No entanto, se a mutação não tivesse o autor no conjunto de seleção, o assinante obteria um valor null para o campo autor (ou um erro, caso o campo de autor fosse definido como necessário/não nulo no esquema).

O conjunto de seleção de assinaturas é essencial ao usar pure WebSockets. Se um campo não estiver definido explicitamente na assinatura, AWS AppSync não retornará o campo.

No exemplo anterior, as assinaturas não tinham argumentos. Digamos que o seu esquema tenha a seguinte aparência:

type Subscription {
    updatedPost(id:ID! author:String): Post
    @aws_subscribe(mutations: ["updatePost"])
}

Nesse caso, o cliente define uma assinatura da seguinte forma:

subscription UpdatedPostSub {
    updatedPost(id:"XYZ", author:"ABC") {
        title
        content
    }
}

O tipo de retorno de um campo do subscription no esquema deve corresponder ao tipo de retorno do campo de mutação correspondente. No exemplo anterior, isso foi mostrado como addPost e addedPost retornados como um tipo de Post.

Para configurar assinaturas no cliente, consulte Criar uma aplicação cliente.

Usar argumentos de assinatura

Uma parte importante do uso de assinaturas do GraphQL é entender quando e como usar argumentos. Você pode fazer alterações sutis para modificar como e quando notificar os clientes sobre as mutações que ocorreram. Para fazer isso, consulte o esquema de amostra do capítulo de início rápido, que cria "Todos". Para este exemplo de esquema, são definidas as seguintes mutações:

type Mutation {
    createTodo(input: CreateTodoInput!): Todo
    updateTodo(input: UpdateTodoInput!): Todo
    deleteTodo(input: DeleteTodoInput!): Todo
}

No exemplo padrão, os clientes podem assinar atualizações de qualquer Todo usando o onUpdateTodo subscription sem argumentos:

subscription OnUpdateTodo {
  onUpdateTodo {
    description
    id
    name
    when
  }
}

Você pode filtrar seu subscription usando seus argumentos. Por exemplo, para acionar somente um subscription quando um todo com um ID específico for atualizado, especifique o valor de ID:

subscription OnUpdateTodo {
  onUpdateTodo(id: "a-todo-id") {
    description
    id
    name
    when
  }
}

Você também pode enviar vários argumentos. Por exemplo, o seguinte subscription demonstra como receber notificações sobre qualquer atualização do Todo em um local e horário específicos:

subscription todosAtHome {
  onUpdateTodo(when: "tomorrow", where: "at home") {
    description
    id
    name
    when
    where
  }
}

Observe que todos os argumentos são opcionais. Se você não especificar nenhum argumento em seu subscription, será inscrito em todas as atualizações do Todo que ocorrerem em seu aplicativo. No entanto, você pode atualizar sua definição do campo do subscription para exigir o argumento do ID. Isso forçaria a resposta de um todo específico em vez de todos os todos:

onUpdateTodo(
  id: ID!,
  name: String,
  when: String,
  where: String,
  description: String
): Todo

Valor de argumento nulo tem significado

Ao fazer uma consulta de assinatura no AWS AppSync, um valor de argumento null filtrará os resultados de forma diferente, não omitindo o argumento totalmente.

Vamos voltar ao exemplo da API todos, onde poderíamos criar todos. Veja o esquema de amostra no capítulo de início rápido.

Vamos modificar nosso esquema para incluir um novo campo de owner, no tipo Todo, descrevendo quem é o proprietário. O campo de owner não é obrigatório e só pode ser ativado em UpdateTodoInput. Veja a seguinte versão simplificada do esquema:

type Todo {
  id: ID!
  name: String!
  when: String!
  where: String!
  description: String!
  owner: String
}

input CreateTodoInput {
  name: String!
  when: String!
  where: String!
  description: String!
}

input UpdateTodoInput {
  id: ID!
  name: String
  when: String
  where: String
  description: String
  owner: String
}

type Subscription {
    onUpdateTodo(
        id: ID,
        name: String,
        when: String,
        where: String,
        description: String
    ): Todo @aws_subscribe(mutations: ["updateTodo"])
}

A assinatura a seguir retorna todas as atualizações de Todo:

subscription MySubscription {
  onUpdateTodo {
    description
    id
    name
    when
    where
  }
}

Se você modificar a assinatura anterior para adicionar o argumento do campo owner: null, estará fazendo uma pergunta diferente. Essa assinatura agora registra o cliente para ser notificado sobre todas as atualizações de Todo que não foram fornecidas a um proprietário.

subscription MySubscription {
  onUpdateTodo(owner: null) {
    description
    id
    name
    when
    where
  }
}

nota

De 1º de janeiro de 2022 em diante, o MQTT over WebSockets não está mais disponível como protocolo para assinaturas do GraphQL nas APIs do AWS AppSync. O Pure WebSockets é o único protocolo compatível com o AWS AppSync.

Clientes baseados no SDK do AWS AppSync ou nas bibliotecas do Amplify, lançadas após novembro de 2019, usam automaticamente pure WebSockets por padrão. Atualizar os clientes para a versão mais recente permite que eles usem o mecanismo pure WebSockets do AWS AppSync.

Os pure WebSockets vêm com um tamanho de carga útil maior (240 KB), uma variedade maior de opções de cliente e métricas aprimoradas do CloudWatch. Para obter mais informações sobre como usar clientes pure WebSocket, consulte Criar um cliente WebSocket em tempo real.