Usando assinaturas para aplicativos de dados em tempo real

AWS AppSyncpermite 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 WebSocket segura é 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 gerenciam AWS AppSync continuamente os requisitos de conexão e escalabilidade do aplicativo. As seções a seguir mostrarão como as assinaturas funcionam. AWS AppSync

Diretivas de assinatura do esquema do GraphQL

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

As bibliotecas de AWS Amplify cliente gerenciam 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 com uma assinatura, você pode usar AWS Identity and Access Management (IAM) AWS Lambda, grupos de identidade do Amazon Cognito ou grupos de usuários do Amazon Cognito para autorização em nível de campo. Para controles de acesso refinados em assinaturas, você pode anexar resolvedores aos seus campos de assinatura e executar a lógica usando a identidade do chamador e das fontes de dados. AWS AppSync Para ter mais informações, consulte Configurando autorização e autenticação para proteger seu GraphQL APIs.

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 Service. OpenSearch

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 WebSockets cliente puro, a filtragem do conjunto de seleção é feita por cliente, pois cada cliente pode 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 o pure WebSockets. Se um campo não estiver definido explicitamente na assinatura, AWS AppSync ele não retornará.

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 Construindo um aplicativo cliente usando o cliente Amplify.

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 AWS AppSync, um valor de null argumento filtrará os resultados de forma diferente de omitir totalmente o argumento.

Vamos voltar ao API exemplo de 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

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

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

O Pure WebSockets vem com um tamanho de carga útil maior (240 KB), uma variedade maior de opções de clientes e CloudWatch métricas aprimoradas. Para obter mais informações sobre o uso de WebSocket clientes puros, consulteConstruindo um WebSocket cliente em tempo real.