As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Começando: Criando sua primeira API GraphQL em AWS AppSync Você pode usar o AWS AppSync console para configurar e iniciar uma API GraphQL. O GraphQL APIs geralmente requer três componentes: 1. **Esquema do GraphQL:** trata-se do esquema da API. Ele define os tipos e campos que você pode solicitar quando uma operação é executada. Para preencher o esquema com dados, você deve conectar as fontes de dados à API do GraphQL. Neste guia de início rápido, criaremos um esquema usando um modelo predefinido. 1. **Fontes de dados:** são os recursos que contêm os dados para preencher a API do GraphQL. Isso pode ser uma tabela do DynamoDB, uma função Lambda, etc AWS AppSync . Suporta uma infinidade de fontes de dados para criar um GraphQL robusto e escalável. APIs As fontes de dados estão vinculadas aos campos no esquema. Sempre que uma solicitação é executada em um campo, os dados da fonte preenchem o campo. Esse mecanismo é controlado pelo resolvedor. Neste guia de início rápido, criaremos uma fonte de dados usando um modelo predefinido juntamente com o esquema. 1. **Resolvedores:** os resolvedores são responsáveis por vincular o campo do esquema à fonte de dados. Eles recuperam os dados da fonte e retornam o resultado com base no que foi definido pelo campo. AWS AppSync suporta ambos JavaScript e VTL para escrever resolvedores para seu GraphQL. APIs Neste guia de início rápido, os resolvedores serão gerados automaticamente com base no esquema e na fonte de dados. Não vamos nos aprofundar nisso nesta seção. AWS AppSync suporta a criação e configuração de todos os componentes do GraphQL. Ao abrir o console, você pode usar os seguintes métodos para criar a API: 1. Projetar uma API do GraphQL personalizada gerando-a por meio de um modelo predefinido e configurando uma nova tabela do DynamoDB (fonte de dados) para suportá-la. 1. Projetando uma API do GraphQL com um esquema em branco e sem fontes de dados ou resolvedores. 1. Usando uma tabela do DynamoDB para importar dados e gerar os tipos e campos do esquema. 1. Usando AWS AppSync os WebSocket recursos e a Pub/Sub arquitetura da para desenvolver em tempo real APIs. 1. Usando o GraphQL existente APIs (fonte APIs) para vincular a uma API mesclada. **nota** Recomendamos ler a seção [Criar um esquema](designing-your-schema.md#aws-appsync-designing-your-schema) antes de trabalhar com ferramentas mais avançadas. Esses guias explicarão exemplos mais simples que você pode usar conceitualmente para criar aplicativos mais complexos. AWS AppSync AWS AppSync também suporta várias opções que não são de console para criar o GraphQL APIs. Isso inclui: 1. AWS Amplify 1. AWS SAM 1. CloudFormation 1. O CDK O exemplo a seguir mostrará como criar os componentes básicos de uma API do GraphQL usando modelos predefinidos e o DynamoDB. **Topics** + [Como iniciar um esquema](schema-launch-start.md) + [Fazendo um tour pelo AWS AppSync console](console-tour.md) + [Uso de mutações do GraphQL para adicionar dados a uma tabela do DynamoDB](add-data-with-graphql-mutation.md) + [Uso de consultas do GraphQL para recuperar dados de uma tabela do DynamoDB](retrieve-data-with-graphql-query.md) + [Seções complementares](next-steps.md) # Iniciando um esquema no console AWS AppSync Neste exemplo, você criará uma `Todo` API que permite aos usuários criar `Todo` itens para lembretes de tarefas diárias, como *Finish task* ou. *Pick up groceries* Essa API demonstrará como usar operações do GraphQL em que o estado é mantido em uma tabela do DynamoDB. Conceitualmente, há três etapas principais para criar sua primeira API do GraphQL. Você deve definir o esquema (tipos e campos), anexar as fontes de dados aos campos e, em seguida, gravar o resolvedor que manipula a lógica de negócios. No entanto, a experiência do console muda essa ordem. Começaremos definindo como queremos que a fonte de dados interaja com o esquema e, em seguida, definiremos o esquema e o resolvedor posteriormente. **Para criar a API do GraphQL** 1. Faça login no Console de gerenciamento da AWS e abra o [AppSync console](https://console.aws.amazon.com/appsync/). 1. No **Painel**, escolha **Criar API**. 1. Enquanto o **GraphQL APIs** estiver selecionado, escolha **Design do zero**. Em seguida, escolha **Avançar**. 1. Em **Nome da API**, altere o nome pré-preenchido para **Todo API** e escolha **Avançar**. **nota** Também há outras opções presentes aqui, mas não as usaremos neste exemplo. 1. Na seção **Especificar recursos do GraphQL**, faça o seguinte: 1. Escolha **Criar tipo com apoio de uma tabela do DynamoDB agora**. **nota** Isso significa que vamos criar uma tabela do DynamoDB para anexar como fonte de dados. 1. No campo **Nome do modelo**, insira **Todo**. **nota** Nosso primeiro requisito é definir o esquema. O **Nome do modelo** será o nome do tipo. Sendo assim, você está criando uma `type` chamada `Todo` que existirá no esquema: ``` type Todo {} ``` 1. Em **Campos**, faça o seguinte: 1. Crie um campo chamado **id**, com o tipo `ID` e obrigatório definido como `Yes`. **nota** Esses são os campos que estarão dentro do escopo do tipo `Todo`. O nome do campo aqui será chamado de `id` com o tipo `ID!`: ``` type Todo { id: ID! } ``` AWS AppSync suporta vários valores escalares para diferentes casos de uso. 1. Em **Adicionar novo campo**, crie quatro campos adicionais com os valores de `Name` definidos como **name**, **when**, **where** e **description**. Os valores de `Type` serão `String`, e os valores de `Array` e `Required` serão `No`. Será algo semelhante a: ![\[Model information form showing fields for a Todo model with ID, name, when, where, and description.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/model-information-tutorial.png) **nota** O tipo completo e seus campos serão semelhantes a: ``` type Todo { id: ID! name: String when: String where: String description: String } ``` Como estamos criando um esquema usando o modelo predefinido, ele também será preenchido com várias mutações padronizadas com base no tipo, como `create`, `delete` e `update` para ajudar você a preencher sua fonte de dados com facilidade. 1. Em **configurar tabela de modelo**, insira um nome de tabela, como **TodoAPITable**. Defina a **Chave primária** como `id`. **nota** Basicamente, estamos criando uma nova tabela do DynamoDB *TodoAPITable* chamada que será anexada à API como nossa principal fonte de dados. Nossa chave primária é definida como o campo `id` obrigatório que definimos antes disso. Observe que essa nova tabela está em branco e não contém dados, exceto a chave de partição. 1. Escolha **Avançar**. 1. Verifique suas alterações e selecione **Criar API**. Espere um momento para que o AWS AppSync serviço termine de criar sua API. Você criou com sucesso uma API do GraphQL com o esquema e a fonte de dados do DynamoDB. Para resumir as etapas acima, optamos por criar uma API do GraphQL completamente nova. Definimos o nome da API e, em seguida, adicionamos nossa definição de esquema adicionando o primeiro tipo. Definimos o tipo e os respectivos campos e, em seguida, optamos por anexar uma fonte de dados a um dos campos criando uma tabela do DynamoDB sem dados. # Fazendo um tour pelo AWS AppSync console Antes de adicionarmos dados à nossa tabela do DynamoDB, devemos analisar os recursos básicos da experiência do AWS AppSync console. A guia do AWS AppSync console no lado esquerdo da página permite que os usuários naveguem facilmente até qualquer um dos principais componentes ou opções de configuração que AWS AppSync fornecem: ![\[AWS AppSync console navigation menu showing APIs, Todo API options, and Documentation link.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/explorer-example-5.jpg) ## Designer do esquema Escolha **Esquema** para visualizar o esquema que você acabou de criar. Se você revisar o conteúdo do esquema, notará que ele já foi carregado com várias operações auxiliares para simplificar o processo de desenvolvimento. No editor **Esquema**, se você percorrer o código, acabará alcançando o modelo definido na seção anterior: ``` type Todo { id: ID! name: String when: String where: String description: String } ``` Seu modelo passou a ser o tipo básico usado em todo o esquema. Começaremos adicionando dados à nossa fonte de dados usando mutações que foram geradas automaticamente a partir desse tipo. Veja abaixo algumas dicas e fatos adicionais sobre o editor **Esquema**: 1. O editor de código tem recursos de verificação de erros e lint que podem ser usados ao gravar seus próprios aplicativos. 1. O lado direito do console mostra os tipos do GraphQL que foram criados e os resolvedores em diferentes tipos de nível superior, como consultas. 1. Ao adicionar novos tipos a um esquema (por exemplo,`type User {...}`), você pode AWS AppSync provisionar recursos do DynamoDB para você. Eles incluem a chave primária, a chave de classificação e o design de índice adequados para melhor corresponder ao padrão de acesso aos dados do GraphQL. Se escolher **Criar recursos** na parte superior e selecionar um desses tipos definidos pelo usuário no menu, você poderá escolher opções de campo diferentes no design do esquema. Abordaremos isso na seção [Criar um esquema](designing-your-schema.md#aws-appsync-designing-your-schema). ### Configuração do resolvedor No designer do esquema, a seção **Resolvedores** contém todos os tipos e campos do esquema. Se você percorrer a lista de campos, notará que pode anexar resolvedores a determinados campos escolhendo **Anexar**. Isso abrirá um editor de código no qual você poderá escrever seu código de resolução. AWS AppSync suporta VTL e JavaScript tempos de execução, que podem ser alterados na parte superior da página escolhendo **Ações** e, em seguida, **Atualizar** Tempo de Execução. Na parte inferior da página, você também pode criar funções que executarão várias operações em uma sequência. No entanto, resolvedores são um tópico avançado, e não o abordaremos nesta seção. ## Fontes de dados Escolha **Fontes de dados** para visualizar a tabela do DynamoDB. Ao escolher a opção `Resource` (se disponível), você poderá visualizar a configuração da fonte de dados. No exemplo, isso leva ao console do DynamoDB. Nele, você pode editar seus dados. Também é possível editar diretamente alguns dos dados. Para isso, escolha a fonte de dados e, em seguida, **Editar**. Se precisar excluir a fonte de dados, você poderá escolher a fonte de dados e selecionar **Excluir**. Por fim, você pode criar fontes de dados escolhendo **Criar fonte de dados** e configurando o nome e o tipo. Observe que essa opção serve para vincular o AWS AppSync serviço a um recurso existente. Você ainda precisa criar o recurso em sua conta usando o serviço relevante antes de AWS AppSync reconhecê-lo. ## Consultas Escolha **Consultas** para ver suas consultas e mutações. Quando criamos nossa API GraphQL usando nosso modelo, geramos AWS AppSync automaticamente algumas mutações e consultas auxiliares para fins de teste. No editor de consultas, o lado esquerdo contém o **Explorador**. Trata-se de uma lista que mostra todas as mutações e consultas. Você pode habilitar facilmente as operações e os campos que deseja usar aqui clicando nos valores de nome. Isso fará com que o código apareça automaticamente na parte central do editor. Aqui, você pode editar as mutações e consultas modificando os valores. Na parte inferior do editor, há o editor **Variáveis de consulta**, que permite inserir os valores dos campos para as variáveis de entrada de suas operações. Escolher **Executar** na parte superior do editor abrirá uma lista suspensa para selecionar query/mutation a ser executada. A saída para essa execução aparecerá no lado direito da página. De volta à seção **Explorador**, na parte superior, você pode escolher uma operação (Consulta, Mutação, Assinatura) e, em seguida, escolher o símbolo **\$1** para adicionar uma nova instância da operação em questão. Na parte superior da página, haverá outra lista suspensa que contém o modo de autorização para a execução de sua consulta. No entanto, não abordaremos esse atributo nesta seção. Para obter mais informações, consulte [Segurança](security-authz.md#aws-appsync-security). ## Configurações Escolha **Configurações** para ver algumas opções de configuração para a API do GraphQL. Aqui, você pode ativar algumas opções, como log, rastreamento e funcionalidade de firewall de aplicativos da web. Você também pode adicionar novos modos de autorização para proteger os dados contra vazamentos indesejados para o público. No entanto, essas opções são mais avançadas e não serão abordadas nesta seção. **nota** O modo de autorização padrão, `API_KEY`, usa uma chave da API para testar o aplicativo. Essa é a autorização básica concedida a todo o APIs GraphQL recém-criado. Recomendamos usar outro método de produção. Para fins de exemplo nesta seção, usaremos somente a chave de API. Para obter mais informações sobre os métodos de autorização aceitos, consulte [Segurança](security-authz.md#aws-appsync-security). # Usando mutações do GraphQL para adicionar dados a uma tabela do DynamoDB no console AWS AppSync Sua próxima etapa é adicionar dados à tabela em branco do DynamoDB usando uma mutação do GraphQL. As mutações são um dos tipos de operação fundamentais no GraphQL. Elas são definidas no esquema e permitem que você manipule dados na fonte de dados. Em termos de REST APIs, elas são muito semelhantes a operações como `PUT` ou`POST`. **Para adicionar a fonte de dados** 1. Se você ainda não tiver feito isso, entre no Console de gerenciamento da AWS e abra o [AppSync console](https://console.aws.amazon.com/appsync/). 1. Escolha sua API na tabela. 1. Na guia à esquerda, escolha **Consultas**. 1. Na guia **Explorador** à esquerda da tabela, você pode ver várias mutações e consultas já definidas no editor de consultas: ![\[Explorer tab showing a dropdown menu with mutation and query options like createTodo and deleteTodo.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/explorer-example-1.png) **nota** Na verdade, essa mutação está no esquema como o tipo do `Mutation`. Ela tem o código: ``` type Mutation { createTodo(input: CreateTodoInput!): Todo updateTodo(input: UpdateTodoInput!): Todo deleteTodo(input: DeleteTodoInput!): Todo } ``` Como você pode ver, as operações aqui são semelhantes àquelas do editor de consultas. AWS AppSync os gerou automaticamente a partir do modelo que definimos anteriormente. Este exemplo usará a `createTodo` mutação para adicionar entradas à nossa *TodoAPITable* tabela. 1. Escolha a operação do `createTodo` expandindo-a sob a mutação do `createTodo`: ![\[Expanded createTodo mutation showing input fields like description, id, name, when, and where.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/explorer-example-2.png) Ative as caixas de seleção de todos os campos, como na imagem acima. **nota** Os atributos exibidos aqui são os diferentes elementos modificáveis da mutação. Seu `input` pode ser considerado como parâmetro de `createTodo`. As várias opções com caixas de seleção são os campos que serão retornados na resposta quando uma operação for executada. 1. No editor de código no centro da tela, você notará que a operação aparece abaixo da mutação do `createTodo`: ``` mutation createTodo($createtodoinput: CreateTodoInput!) { createTodo(input: $createtodoinput) { where when name id description } } ``` **nota** Para explicar esse trecho corretamente, também precisamos examinar o código do esquema. A declaração `mutation createTodo($createtodoinput: CreateTodoInput!){}` é a mutação com uma de suas operações,`createTodo`. A mutação completa está localizada no esquema: ``` type Mutation { createTodo(input: CreateTodoInput!): Todo updateTodo(input: UpdateTodoInput!): Todo deleteTodo(input: DeleteTodoInput!): Todo } ``` Voltando à declaração de mutação do editor, o parâmetro é um objeto chamado `$createtodoinput` com um tipo de entrada obrigatório de `CreateTodoInput`. Observe que `CreateTodoInput` (e todas as entradas na mutação) também são definidas no esquema. Por exemplo, aqui está o código clichê para `CreateTodoInput`: ``` input CreateTodoInput { name: String when: String where: String description: String } ``` Ele contém os campos que definimos em nosso modelo, chamados `name`, `when`, `where` e `description`. Voltando ao código do editor, em `createTodo(input: $createtodoinput) {}`, declaramos a entrada como `$createtodoinput`, que também foi usada na declaração de mutação. Fazemos isso porque isso permite que o GraphQL valide nossas entradas em relação aos tipos fornecidos e garanta que elas estejam sendo usadas com as entradas corretas. A parte final do código do editor mostra os campos que serão retornados na resposta após a execução de uma operação: ``` { where when name id description } ``` Na guia **Variáveis de consulta** abaixo do editor, haverá um objeto do `createtodoinput` que pode ter os seguintes dados: ``` { "createtodoinput": { "name": "Hello, world!", "when": "Hello, world!", "where": "Hello, world!", "description": "Hello, world!" } } ``` **nota** É aqui que alocamos os valores para a entrada mencionada anteriormente: ``` input CreateTodoInput { name: String when: String where: String description: String } ``` Altere o `createtodoinput` adicionando as informações que queremos colocar na tabela do DynamoDB. Nesse caso, queríamos criar alguns itens do `Todo` como lembretes: ``` { "createtodoinput": { "name": "Shopping List", "when": "Friday", "where": "Home", "description": "I need to buy eggs" } } ``` 1. Escolha **Executar** na parte superior do editor. Escolha **createTodo** na lista suspensa. No lado direito do editor, você verá a resposta. Essa lista pode ser semelhante a: ``` { "data": { "createTodo": { "where": "Home", "when": "Friday", "name": "Shopping List", "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "description": "I need to buy eggs" } } } ``` Se você navegar até o serviço do DynamoDB, agora verá uma entrada na fonte de dados com as seguintes informações: ![\[TodoAPITable interface showing a completed scan with 1 item returned in a table format.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/explorer-example-3.png) Para resumir a operação, o mecanismo GraphQL analisou o registro, e um resolvedor o inseriu na tabela do Amazon DynamoDB. Você pode verificar isso no console. Observe que não é preciso enviar um valor de `id`. Um `id` é gerado e retornado nos resultados. Isso ocorre porque o exemplo usou uma função de `autoId()` em um resolvedor do GraphQL para a chave de partição definida nos recursos do DynamoDB. Abordaremos como você pode criar resolvedores em uma seção diferente. Anote o valor do `id` retornado; você o usará na próxima seção para recuperar dados com uma consulta do GraphQL. # Usando consultas do GraphQL para recuperar dados de uma tabela do DynamoDB no console AWS AppSync Agora que há um registro no banco de dados, você obterá resultados ao executar uma consulta. Uma consulta é uma das outras operações fundamentais do GraphQL. Ela é usada para analisar e recuperar informações da fonte de dados. Em termos de REST APIs, isso é semelhante à `GET` operação. A principal vantagem das consultas do GraphQL é a capacidade de especificar os requisitos de dados exatos do aplicativo para que você busque os dados relevantes no momento certo. **Para consultar a fonte de dados** 1. Se você ainda não tiver feito isso, entre no Console de gerenciamento da AWS e abra o [AppSync console](https://console.aws.amazon.com/appsync/). 1. Escolha sua API na tabela. 1. Na guia à esquerda, escolha **Consultas**. 1. Na guia **Explorador** à esquerda da tabela, abaixo de `query``listTodos`, expanda a operação do `getTodo`: ![\[Expanded getTodo operation showing fields id, description, name, when, and where.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/explorer-example-4.png) 1. No editor de código, você deverá ver o código da operação: ``` query listTodos { getTodo(id: "") { description id name when where } ``` Em `(id:"")`, preencha o valor que você salvou no resultado da operação de mutação. Neste exemplo, o resultado seria . ``` query listTodos { getTodo(id: "abcdefgh-1234-1234-1234-abcdefghijkl") { description id name when where } ``` 1. Escolha **Executar** e, em seguida, **listTodos**. O resultado aparecerá à direita do editor. Nosso exemplo ficou semelhante a: ``` { "data": { "getTodo": { "description": "I need to buy eggs", "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "name": "Shopping List", "when": "Friday", "where": "Home" } } } ``` **nota** As consultas retornam apenas os campos especificados. Você pode desmarcar os campos desnecessários excluindo-os do campo de retorno: ``` { description id name when where } ``` Você também pode desmarcar a caixa na guia **Explorador** ao lado do campo que você deseja excluir. 1. Você também pode tentar a operação do `listTodos` repetindo as etapas para criar uma entrada na fonte de dados e, em seguida, repetindo as etapas de consulta com a operação do `listTodos`. Veja um exemplo em que adicionamos uma segunda tarefa: ``` { "createtodoinput": { "name": "Second Task", "when": "Monday", "where": "Home", "description": "I need to mow the lawn" } } ``` Ao chamar a operação do `listTodos`, ela retornou as entradas antigas e novas: ``` { "data": { "listTodos": { "items": [ { "id": "abcdefgh-1234-1234-1234-abcdefghijkl", "name": "Shopping List", "when": "Friday", "where": "Home", "description": "I need to buy eggs" }, { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "name": "Second Task", "when": "Monday", "where": "Home", "description": "I need to mow the lawn" } ] } } } ``` # Seções complementares para o console AWS AppSync Essas seções são uma referência para AWS AppSync tópicos mais avançados. Recomendamos seguir a seção *Leitura suplementar* antes de realizar qualquer outra ação. ## Integração Na guia do console, se você escolher o nome da API, a página **Integração** será exibida: ![\[AWS AppSync sidebar menu with APIs, Todo API highlighted, and other options listed.\]](http://docs.aws.amazon.com/pt_br/appsync/latest/devguide/images/explorer-example-6.png) Ela resume as etapas para configurar a API e descreve as próximas etapas para criar um aplicativo cliente. A seção **Integrar com seu aplicativo** fornece detalhes sobre como usar o conjunto de [ferramentas do AWS Amplify](https://aws-amplify.github.io/) para automatizar o processo de conexão da sua API com iOS, Android e JavaScript aplicativos por meio de configuração e geração de código. A cadeia de ferramentas do Amplify oferece suporte total à criação de projetos a partir da estação de trabalho local, incluindo o provisionamento do GraphQL e fluxos de trabalho para CI/CD. A seção **Amostras** de clientes também lista exemplos de aplicativos cliente (por exemplo JavaScript, iOS, Android) para testar uma end-to-end experiência. É possível clonar e fazer download das amostras e do arquivo de configuração que contém as informações necessárias (como o URL do endpoint) de que precisa para começar a usar. Siga as instruções na página [Cadeia de ferramentas do AWS Amplify](https://aws-amplify.github.io/) para executar o aplicativo. ## Leitura complementar + [Projetando o GraphQL APIs com AWS AppSync](designing-a-graphql-api.md) - Este é um guia completo para criar seu GraphQL usando um esquema em branco sem fontes de dados ou resolvedores.