Tipos no GraphQL

As consultas são muito semelhantes às operações GET, pois realizam uma busca somente para leitura para obter dados da sua fonte. No GraphQL, a Query define todos os pontos de entrada para clientes que fazem solicitações em seu servidor. Sempre haverá um Query em sua implementação do GraphQL.

Aqui estão os tipos Query de objetos modificados que usamos em nosso exemplo de esquema anterior:

type Person { 
  id: ID!
  name: String
  age: Int
  occupation: Occupation
}
type Occupation {
  title: String
}
type Query {                                   
  people: [Person]
}

Nosso Query contém um campo chamado people que retorna uma lista de instâncias Person da fonte de dados. Digamos que precisemos mudar o comportamento do nosso aplicativo e agora precisamos retornar uma lista somente das instâncias de Occupation para algum propósito separado. Poderíamos simplesmente adicioná-lo à consulta:

type Query {                                   
  people: [Person]
  occupations: [Occupation]
}

No GraphQL, podemos tratar nossa consulta como a única fonte de solicitações. Como você pode ver, isso pode ser muito mais simples do que implementações RESTful que podem usar endpoints diferentes para alcançar a mesma coisa (.../api/1/people e .../api/1/occupations).

Supondo que tenhamos uma implementação de resolvedor para essa consulta, agora podemos realizar uma consulta real. Embora o tipo Query exista, precisamos chamá-lo explicitamente para que ele seja executado no código do aplicativo. Isso pode ser feito usando a palavra-chave query:

query getItems {
   people {
      name
   }
   occupations {
      title
   }
}

Como você pode ver, essa consulta é chamada getItems e retorna people (uma lista de objetos Person) e occupations (uma lista de objetos Occupation). Em people, estamos retornando somente o campo name de cada Person, enquanto retornamos o campo title de cada Occupation. A resposta pode ser semelhante a:

{
  "data": {
    "people": [
      {
        "name": "John Smith"
      },
      {
        "name": "Andrew Miller"
      },
      .
      .
      .
    ],
    "occupations": [
      {
        "title": "Firefighter"
      },
      {
        "title": "Bookkeeper"
      },
      .
      .
      .
    ]
  }
}

O exemplo de resposta mostra como os dados seguem a forma da consulta. Cada entrada recuperada é listada dentro do escopo do campo. people e occupations estão retornando itens como listas separadas. Embora isso seja útil, talvez seja mais conveniente modificar a consulta para retornar uma lista dos nomes e ocupações das pessoas:

query getItems {
   people {
      name   
      occupation {
        title
      }
}

Essa é uma modificação legal porque nosso tipo Person contém um campo occupation de tipo Occupation. Quando listados no escopo de people, retornamos cada um name de Person junto com os Occupation associados por title. A resposta pode ser semelhante a:

}
  "data": {
    "people": [
      {
        "name": "John Smith",
        "occupation": {
          "title": "Firefighter"
        }
      },
      {
        "name": "Andrew Miller",
        "occupation": {
          "title": "Bookkeeper"
        }
      },
      .
      .
      .
    ]
  }
}

As mutações são semelhantes às operações de alteração de estado, como ou PUT POST. Eles realizam uma operação de gravação para modificar os dados na fonte e, em seguida, buscam a resposta. Eles definem seus pontos de entrada para solicitações de modificação de dados. Diferentemente das consultas, uma mutação pode ou não ser incluída no esquema, dependendo das necessidades do projeto. Veja a mutação do exemplo do esquema:

type Mutation {
  addPerson(id: ID!, name: String, age: Int): Person
}

O campo addPerson representa um ponto de entrada que adiciona uma Person à fonte de dados. addPerson é o nome do campo; id,name e age são os parâmetros; e Person é o tipo de retorno. Relembrando o tipo Person:

type Person { 
  id: ID!
  name: String
  age: Int
  occupation: Occupation
}

Adicionamos o campo occupation. No entanto, não podemos definir esse campo como Occupation diretamente porque os objetos não podem ser passados como argumentos; eles são estritamente tipos de saída. Em vez disso, devemos passar uma entrada com os mesmos campos de um argumento:

input occupationInput {
  title: String
}

Também podemos atualizar facilmente nosso addPerson para incluir isso como um parâmetro ao criar novas instâncias de Person:

type Mutation {
  addPerson(id: ID!, name: String, age: Int, occupation: occupationInput): Person
}

Veja o esquema atualizado:

type Person { 
  id: ID!
  name: String
  age: Int
  occupation: Occupation
}

type Occupation {
  title: String
}

input occupationInput {
  title: String
}

type Mutation {
  addPerson(id: ID!, name: String, age: Int, occupation: occupationInput): Person
}

Observe que occupation passará o campo title de occupationInput para concluir a criação do objeto Person em vez do Occupation original. Supondo que tenhamos uma implementação de resolvedor para addPerson, agora podemos realizar uma mutação real. Embora o tipo Mutation exista, precisamos chamá-lo explicitamente para que ele seja executado no código do aplicativo. Isso pode ser feito usando a palavra-chave mutation:

mutation createPerson {
  addPerson(id: ID!, name: String, age: Int, occupation: occupationInput) {
    name
    age
    occupation {
      title
    }
  }
}

Essa mutação é chamada de createPerson, e addPerson é a operação. Para criar uma nova Person, podemos inserir os argumentos para id, name, age e occupation. No escopo de addPerson, também podemos ver outros campos como name, age, etc. Esta é sua resposta; esses são os campos que serão retornados após a conclusão da operação addPerson. Aqui está a parte final do exemplo:

mutation createPerson {
  addPerson(id: "1", name: "Steve Powers", age: "50", occupation: "Miner") {
    id
    name
    age
    occupation {
      title
    }
  }
}

Usando essa mutação, o resultado pode ser semelhante a:

{
  "data": {
    "addPerson": {
      "id": "1",
      "name": "Steve Powers",
      "age": "50",
      "occupation": {
        "title": "Miner"
      }
    }
  }
}

Como você pode ver, a resposta retornou os valores que solicitamos no mesmo formato definido em nossa mutação. A prática recomendada é retornar todos os valores que foram modificados para reduzir a confusão e a necessidade de mais consultas no futuro. As mutações permitem que você inclua várias operações em seu escopo. Eles serão executados sequencialmente na ordem listada na mutação. Por exemplo, se criarmos outra operação chamada addOccupation que adiciona cargos à fonte de dados, podemos chamar isso na mutação depois de addPerson. addPerson será tratado primeiro, seguido por addOccupation.

As assinaturas usam WebSockets para abrir uma conexão bidirecional duradoura entre o servidor e seus clientes. Normalmente, um cliente assina ou escuta o servidor. Sempre que o servidor fizer uma alteração no servidor ou realizar um evento, o cliente assinante receberá as atualizações. Esse tipo de protocolo é útil quando vários clientes são assinantes e precisam ser notificados sobre alterações que estão acontecendo no servidor ou em outros clientes. Por exemplo, as assinaturas podem ser usadas para atualizar feeds de mídia social. Pode haver dois usuários, o usuário A e o usuário B, que são assinantes das atualizações automáticas de notificação sempre que recebem mensagens diretas. O usuário A no cliente A poderia enviar uma mensagem direta para o usuário B no cliente B. O cliente do usuário A enviaria a mensagem direta, que seria processada pelo servidor. O servidor então enviaria a mensagem direta para a conta do Usuário B enquanto enviaria uma notificação automática para o Cliente B.

Aqui está um exemplo de uma Subscription que poderíamos adicionar ao exemplo do esquema:

type Subscription {                                   
  personAdded: Person
}

O campo personAdded enviará uma mensagem aos clientes inscritos sempre que uma nova Person for adicionada à fonte de dados. Supondo que tenhamos uma implementação de resolvedor para personAdded, agora podemos usar a assinatura. Embora o tipo Subscription exista, precisamos chamá-lo explicitamente para que ele seja executado no código do aplicativo. Isso pode ser feito usando a palavra-chave subscription:

subscription personAddedOperation {
  personAdded {
    id
    name
  }
}

A assinatura é chamada de personAddedOperation e a operação é personAdded. personAddedretornará os campos id e name de novas instâncias de Person. Analisando o exemplo de mutação, adicionamos uma Person usando esta operação:

addPerson(id: "1", name: "Steve Powers", age: "50", occupation: "Miner")

Se nossos clientes tiverem assinatura para receber atualizações da Person recém-adicionada, eles poderão ver isso após as execuções de addPerson:

{
  "data": {
    "personAdded": {
      "id": "1",
      "name": "Steve Powers"
    }
  }
}

Veja abaixo um resumo do que as assinaturas oferecem:

As assinaturas são canais bidirecionais que permitem que o cliente e o servidor recebam atualizações rápidas, mas constantes. Elas normalmente usam o protocolo WebSocket, que cria conexões padronizadas e seguras.

As assinaturas são ágeis, pois reduzem a sobrecarga de configuração da conexão. Depois de fazer uma assinatura, o cliente pode continuar executando essa assinatura por longos períodos. Eles geralmente usam recursos de computação de forma eficiente, permitindo que os desenvolvedores personalizem a vida útil da assinatura e configurem quais informações serão solicitadas.

No geral, o cliente pode fazer várias assinaturas ao mesmo tempo. No que diz respeito ao AWS AppSync, as assinaturas são usadas apenas para receber atualizações em tempo real do serviço AWS AppSync. Elas não podem ser usadas para realizar consultas ou mutações.

A principal alternativa às assinaturas é a sondagem, que envia consultas em intervalos definidos para solicitar dados. Esse processo geralmente é menos eficiente do que as assinaturas e sobrecarrega muito o cliente e o back-end.

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

.
.
.

type Query {                                   
  # code goes here
}
type Mutation {                                   
  # code goes here
}
type Subscription {                                   
  # code goes here
}