Uso de resolvedores do Amazon OpenSearch Service no AWS AppSync

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 nossa Referência de função do resolvedor de JavaScript para o OpenSearch.

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 Criar fonte de dados 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:

JSON

{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "appsync.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Além disso, o domínio do OpenSearch Service tem sua própria Política de acesso que pode ser modificada por meio do console do Amazon OpenSearch Service. Você deve adicionar uma política semelhante à abaixo 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 AWS AppSync, que pode ser encontrada no console do IAM se você permitir que esse console a crie.

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:

 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. No painel Resolvedores, encontre searchPosts e escolha Anexar. Escolha sua fonte de dados do OpenSearch Service e salve o resolvedor. Atualize o código do seu resolvedor usando o trecho abaixo:

import { util } from '@aws-appsync/utils'

/**
 * Searches for documents by using an input term
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the request
 */
export function request(ctx) {
	return {
		operation: 'GET',
		path: `/post/_search`,
		params: { body: { from: 0, size: 50 } },
	}
}

/**
 * Returns the fetched items
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the result
 */
export function response(ctx) {
	if (ctx.error) {
		util.error(ctx.error.message, ctx.error.type)
	}
	return ctx.result.hits.hits.map((hit) => hit._source)
}

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.

Modificação das pesquisas

O manipulador de solicitação do resolvedor 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]
}

No painel Resolvedores, encontre allPostsByAuthor e escolha Anexar. Escolha a fonte de dados do OpenSearch Service e use o seguinte código:

import { util } from '@aws-appsync/utils'

/**
 * Searches for documents by `author`
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the request
 */
export function request(ctx) {
	return {
		operation: 'GET',
		path: '/post/_search',
		params: {
			body: {
				from: 0,
				size: 50,
				query: { match: { author: ctx.args.author } },
			},
		},
	}
}

/**
 * Returns the fetched items
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the result
 */
export function response(ctx) {
	if (ctx.error) {
		util.error(ctx.error.message, ctx.error.type)
	}
	return ctx.result.hits.hits.map((hit) => hit._source)
}

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 usar informações pré-preenchidas, como texto padrão.

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 pode servir 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 para a mutação addPost(). Selecione a fonte de dados do OpenSearch Service novamente e use o seguinte código:

import { util } from '@aws-appsync/utils'

/**
 * Searches for documents by `author`
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the request
 */
export function request(ctx) {
	return {
		operation: 'PUT',
		path: `/post/_doc/${ctx.args.id}`,
		params: { body: ctx.args },
	}
}

/**
 * Returns the inserted post
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the result
 */
export function response(ctx) {
	if (ctx.error) {
		util.error(ctx.error.message, ctx.error.type)
	}
	return ctx.result
}

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. Este exemplo também mostra como usar context.arguments, que também pode ser escrito como ctx.args, em seu manipulador de solicitações.

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. Selecione a fonte de dados do OpenSearch Service novamente e use o seguinte código:

import { util } from '@aws-appsync/utils'

/**
 * Searches for documents by `author`
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the request
 */
export function request(ctx) {
	return {
		operation: 'GET',
		path: `/post/_doc/${ctx.args.id}`,
	}
}

/**
 * Returns the post
 * @param {import('@aws-appsync/utils').Context} ctx the context
 * @returns {*} the result
 */
export function response(ctx) {
	if (ctx.error) {
		util.error(ctx.error.message, ctx.error.type)
	}
	return ctx.result._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 search {
    searchPosts {
        id
        title
        author
        content
    }
}

Práticas recomendadas