Uso de resolvedores do Amazon OpenSearch Service no AWS AppSync
nota
Agora, oferecemos suporte principalmente ao runtime do APPSYNC_JS e sua documentação. Considere usar o runtime do APPSYNC_JS e seus guias disponíveis aqui.
O AWS AppSync oferece suporte ao uso do Amazon OpenSearch Service a partir de domínios provisionados em sua própria conta da AWS, desde que não existam dentro de uma VPC. Assim que os domínios forem provisionados, conecte-se a eles usando uma fonte de dados, no momento em que pode configurar um resolvedor no esquema para realizar operações do GraphQL, como consultas, mutações e assinaturas. Esse tutorial apresentará alguns exemplos comuns.
Para obter mais informações, consulte a Referência de modelo de mapeamento do resolvedor para OpenSearch.
Configuração com um clique
Para configurar automaticamente um endpoint do GraphQL no AWS AppSync com o Amazon OpenSearch Service configurado, você pode usar este modelo AWS CloudFormation:
Após a conclusão da implantação do AWS CloudFormation você pode pular diretamente para a execução de consultas e mutações do GraphQL.
Criar um domínio do OpenSearch Service
Para começar a usar esse tutorial, você precisa de um domínio existente do OpenSearch Service. Caso não tenha um, use o exemplo a seguir. Observe que pode levar até 15 minutos para que um domínio do OpenSearch Service seja criado antes de poder passar para a integração com uma fonte de dados do AWS AppSync.
aws cloudformation create-stack --stack-name AppSyncOpenSearch \ --template-url https://s3.us-west-2.amazonaws.com/awsappsync/resources/elasticsearch/ESResolverCFTemplate.yaml \ --parameters ParameterKey=OSDomainName,ParameterValue=ddtestdomain ParameterKey=Tier,ParameterValue=development \ --capabilities CAPABILITY_NAMED_IAM
Você pode lançar a seguinte pilha do AWS CloudFormation na região Oeste dos EUA 2 (Oregon) em sua conta da AWS:
Configurar fonte de dados para o OpenSearch Service
Depois que o domínio do OpenSearch Service for criado, navegue até a API AWS AppSync do GraphQL e escolha a guia Fontes de dados. Selecione Novo e insira um nome acessível para a fonte de dados, como "oss". Em seguida, selecione Domínio do Amazon OpenSearch para Tipo de fonte de dados, escolha a região apropriada e você verá seu domínio do OpenSearch Service listado. Depois de selecioná-lo, você pode criar uma nova função e o AWS AppSync atribuirá as permissões adequadas à função, ou selecione uma função existente, com a seguinte política em linha:
Também será necessário configurar uma relação de confiança com o AWS AppSync para essa função:
Além disso, o domínio do OpenSearch Service possui sua própria política de acesso, que você pode modificar por meio do console do Amazon OpenSearch Service. Você precisará adicionar uma política semelhante à seguinte, com as ações e recursos apropriados para o domínio do OpenSearch Service. Observe que o Entidade principal será a função de fonte de dados do AppSync, que, se você permitir que o console crie isso, poderá ser encontrada no console do IAM.
Conexão de um resolvedor
Agora que a fonte de dados está conectada ao domínio do OpenSearch Service, conecte-a ao esquema do GraphQL com um resolvedor, conforme mostrado no exemplo a seguir:
schema { query: Query mutation: Mutation } type Query { getPost(id: ID!): Post allPosts: [Post] } type Mutation { addPost(id: ID!, author: String, title: String, url: String, ups: Int, downs: Int, content: String): AWSJSON } type Post { id: ID! author: String title: String url: String ups: Int downs: Int content: String } ...
Observe que há um tipo Post definido pelo usuário com um campo de id. Nos exemplos a seguir, assumimos que há um processo (que pode ser automatizado) para colocar esse tipo no domínio do OpenSearch Service, o que mapearia para uma raiz de caminho do /post/_doc, onde post é o índice. A partir desse caminho raiz, você pode executar pesquisas de documento individuais, pesquisas com curingas com /id/post* ou pesquisas de vários documentos com um caminho de /post/_search. Por exemplo, se você tiver outro tipo chamado User, poderá indexar documentos em um novo índice chamado user e depois realizar pesquisas com um caminho de /user/_search.
A partir do editor de esquema no console do AWS AppSync, modifique o esquema Posts anterior para incluir uma consulta searchPosts:
type Query { getPost(id: ID!): Post allPosts: [Post] searchPosts: [Post] }
Salve o esquema. À direita, em searchPosts, selecione Anexar resolvedor. No menu Ação, escolha Atualizar runtime e selecione Resolvedor de unidade (somente VTL). Depois, escolha sua fonte de dados do OpenSearch Service. Na seção modelo de mapeamento da solicitação, selecione o menu suspenso em Postagens de consulta para obter um modelo base. Modifique o path para /post/_search. Ele deve ter a seguinte aparência:
{ "version":"2017-02-28", "operation":"GET", "path":"/post/_search", "params":{ "headers":{}, "queryString":{}, "body":{ "from":0, "size":50 } } }
Isso pressupõe que o esquema anterior tenha documentos que foram indexados no OpenSearch Service no campo post. Se você estruturar os dados de forma diferente, será necessário atualizar de forma adequada.
Na seção modelo de mapeamento da resposta, é necessário especificar o filtro _source apropriado se quiser obter os resultados dos dados de volta a partir de uma consulta do OpenSearch Service e traduzir para o GraphQL. Use o modelo a seguir:
[ #foreach($entry in $context.result.hits.hits) #if( $velocityCount > 1 ) , #end $utils.toJson($entry.get("_source")) #end ]
Modificação das pesquisas
O modelo de mapeamento da solicitação anterior executa uma consulta simples para todos os registros. Digamos que você queira pesquisar um autor específico. Além disso, digamos que queira que esse autor seja um argumento definido na consulta do GraphQL. No editor de esquema do console do AWS AppSync, adicione uma consulta allPostsByAuthor:
type Query { getPost(id: ID!): Post allPosts: [Post] allPostsByAuthor(author: String!): [Post] searchPosts: [Post] }
Agora, escolha Anexar resolvedor e selecione a fonte de dados do OpenSearch Service, mas use o exemplo a seguir no modelo de mapeamento da resposta:
{ "version":"2017-02-28", "operation":"GET", "path":"/post/_search", "params":{ "headers":{}, "queryString":{}, "body":{ "from":0, "size":50, "query":{ "match" :{ "author": $util.toJson($context.arguments.author) } } } } }
Observe que o body é preenchido com uma consulta de termo para o campo author, que é enviada a partir do cliente como um argumento. Também é possível ter informações pré-preenchidas, como texto padrão, ou até mesmo usar outros utilitários.
Se estiver usando esse resolvedor, preencha o modelo de mapeamento da resposta com as mesmas informações que o exemplo anterior.
Adição de dados ao OpenSearch Service
Adicione dados ao domínio do OpenSearch Service como resultado de uma mutação do GraphQL. Esse é um poderoso mecanismo para pesquisa e outras finalidades. Como é possível usar assinaturas do GraphQL para tornar seus dados em tempo real, ele serve como um mecanismo para notificar os clientes sobre atualizações de dados no domínio do OpenSearch Service.
Volte para a página Esquema no console do AWS AppSync e selecione Anexar resolvedor para a mutação addPost(). Selecione a fonte de dados do OpenSearch Service novamente e use o seguinte modelo de mapeamento de resposta para o esquema Posts:
{ "version":"2017-02-28", "operation":"PUT", "path": $util.toJson("/post/_doc/$context.arguments.id"), "params":{ "headers":{}, "queryString":{}, "body":{ "id": $util.toJson($context.arguments.id), "author": $util.toJson($context.arguments.author), "ups": $util.toJson($context.arguments.ups), "downs": $util.toJson($context.arguments.downs), "url": $util.toJson($context.arguments.url), "content": $util.toJson($context.arguments.content), "title": $util.toJson($context.arguments.title) } } }
Como antes, este é um exemplo de como os dados podem ser estruturados. Se tiver diferentes nomes de campos ou índices, é necessário atualizar o path e o body conforme apropriado. Esse exemplo também mostra como usar $context.arguments para preencher o modelo a partir dos argumentos da mutação do GraphQL.
Antes de prosseguir, use o seguinte modelo de mapeamento de resposta, que retornará o resultado da operação de mutação ou informações de erro como saída:
#if($context.error) $util.toJson($ctx.error) #else $util.toJson($context.result) #end
Recuperação de um único documento
Por fim, se quiser usar a consulta getPost(id:ID) em seu esquema para retornar um documento individual, encontre essa consulta no editor de esquema do console do AWS AppSync e escolha Anexar resolvedor. Selecione a fonte de dados do OpenSearch Service novamente e use o seguinte modelo de mapeamento:
{ "version":"2017-02-28", "operation":"GET", "path": $util.toJson("post/_doc/$context.arguments.id"), "params":{ "headers":{}, "queryString":{}, "body":{} } }
Como o path acima usa o argumento id com um corpo vazio, isso retorna o único documento. No entanto, é necessário usar o seguinte modelo de mapeamento da resposta, pois agora você está retornando um único item, e não uma lista:
$utils.toJson($context.result.get("_source"))
Executar consultas e mutações
Agora você deve ser capaz de executar operações do GraphQL no domínio do OpenSearch Service. Navegue até a guia Consultas do console do AWS AppSync e adicione um novo registro:
mutation addPost { addPost ( id:"12345" author: "Fred" title: "My first book" content: "This will be fun to write!" url: "publisher website", ups: 100, downs:20 ) }
Você verá o resultado da mutação à direita. Da mesma forma, execute agora consulta searchPosts no domínio do OpenSearch Service:
query searchPosts { searchPosts { id title author content } }
Práticas recomendadas
-
O OpenSearch Service deve servir para a consulta de dados e não como banco de dados primário. Use o OpenSearch Service em conjunto com o Amazon DynamoDB, conforme descrito em Combinar resolvedores do GraphQL.
-
Conceda acesso ao domínio somente ao permitir que o perfil de serviço do AWS AppSync acesse o cluster.
-
Você pode começar pequeno no desenvolvimento, com o cluster de menor custo e, em seguida, migrar para um cluster maior com alta disponibilidade (HA) à medida que entrar na produção.
