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á. # Tutorial: Criando um aplicativo de pesquisa com o Amazon OpenSearch Service Uma forma comum de criar um aplicativo de pesquisa com o Amazon OpenSearch Service é usar formulários da web para enviar consultas de usuários a um servidor. Em seguida, você pode autorizar o servidor a ligar OpenSearch APIs diretamente para o e fazer com que o servidor envie solicitações ao OpenSearch Serviço. No entanto, se desejar escrever um código do lado do cliente que não dependa de um servidor, é necessário compensar os riscos de segurança e performance. Não é aconselhável permitir o acesso público não assinado ao OpenSearch APIs . Os usuários podem acessar endpoints não seguros ou afetar a performance do cluster por meio de consultas excessivamente amplas (ou muitas consultas). Este capítulo apresenta uma solução: use o Amazon API Gateway para restringir os usuários a um subconjunto do OpenSearch APIs e AWS Lambda assinar solicitações do API Gateway para o OpenSearch Service. ![\[Diagrama de fluxo do aplicativo de pesquisa.\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/search-application-diagram.png) **nota** Os preços padrão do API Gateway e do Lambda se aplicam, mas dentro do uso limitado desse tutorial, os custos devem ser insignificantes. ## Pré-requisitos Um pré-requisito para este tutorial é um domínio de OpenSearch serviço. Se você ainda não tiver um, siga as etapas em [Criar um domínio OpenSearch de serviço](gsgcreate-domain.md) para criar um. ## Etapa 1: Indexar dados de exemplo Faça download de [sample-movies.zip](samples/sample-movies.zip) e use a operação da API [\$1bulk](https://opensearch.org/docs/latest/api-reference/document-apis/bulk/) para adicionar os 5.000 documentos ao índice `movies`: ``` POST https://search-my-domain.us-west-1.es.amazonaws.com/_bulk { "index": { "_index": "movies", "_id": "tt1979320" } } {"directors":["Ron Howard"],"release_date":"2013-09-02T00:00:00Z","rating":8.3,"genres":["Action","Biography","Drama","Sport"],"image_url":"http://ia.media-imdb.com/images/M/MV5BMTQyMDE0MTY0OV5BMl5BanBnXkFtZTcwMjI2OTI0OQ@@._V1_SX400_.jpg","plot":"A re-creation of the merciless 1970s rivalry between Formula One rivals James Hunt and Niki Lauda.","title":"Rush","rank":2,"running_time_secs":7380,"actors":["Daniel Brühl","Chris Hemsworth","Olivia Wilde"],"year":2013,"id":"tt1979320","type":"add"} { "index": { "_index": "movies", "_id": "tt1951264" } } {"directors":["Francis Lawrence"],"release_date":"2013-11-11T00:00:00Z","genres":["Action","Adventure","Sci-Fi","Thriller"],"image_url":"http://ia.media-imdb.com/images/M/MV5BMTAyMjQ3OTAxMzNeQTJeQWpwZ15BbWU4MDU0NzA1MzAx._V1_SX400_.jpg","plot":"Katniss Everdeen and Peeta Mellark become targets of the Capitol after their victory in the 74th Hunger Games sparks a rebellion in the Districts of Panem.","title":"The Hunger Games: Catching Fire","rank":4,"running_time_secs":8760,"actors":["Jennifer Lawrence","Josh Hutcherson","Liam Hemsworth"],"year":2013,"id":"tt1951264","type":"add"} ... ``` Observe que o exemplo acima é um comando com um pequeno subconjunto dos dados disponíveis. Para executar a operação `_bulk`, você precisa copiar e colar todo o conteúdo do arquivo `sample-movies`. Para obter instruções adicionais, consulte [Opção 2: carregar vários documentos](gsgupload-data.md#gsgmultiple-document). Também é possível usar o seguinte comando do curl para obter o mesmo resultado: ``` curl -XPOST -u 'master-user:master-user-password' 'domain-endpoint/_bulk' --data-binary @bulk_movies.json -H 'Content-Type: application/json' ``` ## Etapa 2: criar e implantar a função do Lambda Antes de criar sua API no API Gateway, crie a função do Lambda para a qual ela passará as solicitações. ### Criar a função do Lambda Nessa solução, o API Gateway passa solicitações para uma função Lambda, que consulta o OpenSearch Serviço e retorna os resultados. Como essa função de exemplo usa bibliotecas externas, é necessário criar um pacote de implantação e carregar para o Lambda. **Para criar o pacote de implantação** 1. Abra um prompt de comando e crie um diretório de projeto do `my-opensearch-function`. Por exemplo, no macOS: ``` mkdir my-opensearch-function ``` 1. Navegue até o diretório de projeto do `my-sourcecode-function`. ``` cd my-opensearch-function ``` 1. Copie o conteúdo do seguinte código Python de exemplo e salve-o em um novo arquivo chamado `opensearch-lambda.py`. Adicione sua região e o endpoint do host ao arquivo. ``` import boto3 import json import requests from requests_aws4auth import AWS4Auth region = '' # For example, us-west-1 service = 'es' credentials = boto3.Session().get_credentials() awsauth = AWS4Auth(credentials.access_key, credentials.secret_key, region, service, session_token=credentials.token) host = '' # The OpenSearch domain endpoint with https:// and without a trailing slash index = 'movies' url = host + '/' + index + '/_search' # Lambda execution starts here def lambda_handler(event, context): # Put the user query into the query DSL for more accurate search results. # Note that certain fields are boosted (^). query = { "size": 25, "query": { "multi_match": { "query": event['queryStringParameters']['q'], "fields": ["title^4", "plot^2", "actors", "directors"] } } } # Elasticsearch 6.x requires an explicit Content-Type header headers = { "Content-Type": "application/json" } # Make the signed HTTP request r = requests.get(url, auth=awsauth, headers=headers, data=json.dumps(query)) # Create the response and add some extra content to support CORS response = { "statusCode": 200, "headers": { "Access-Control-Allow-Origin": '*' }, "isBase64Encoded": False } # Add the search results to the response response['body'] = r.text return response ``` 1. Instale a biblioteca externa em um novo diretório de `package`. ``` pip3 install --target ./package boto3 pip3 install --target ./package requests pip3 install --target ./package requests_aws4auth ``` 1. Crie um pacote de implantação com a biblioteca instalada na raiz. O seguinte comando gera um arquivo `my-deployment-package.zip` no diretório do projeto. ``` cd package zip -r ../my-deployment-package.zip . ``` 1. Adicione o arquivo `opensearch-lambda.py` à raiz do arquivo zip. ``` cd .. zip my-deployment-package.zip opensearch-lambda.py ``` Para saber mais sobre a criação de funções do Lambda e pacotes de implantação, consulte [Implantar funções do Lambda em Python com arquivos .zip](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python-how-to-create-deployment-package.html) no *Guia do desenvolvedor do AWS Lambda * e [Criar o pacote de implantação do Lambda](integrations-s3-lambda.md#integrations-s3-lambda-deployment-package) neste guia. Para criar sua função usando o console do Lambda 1. [Navegue até o console Lambda em casahttps://console.aws.amazon.com/lambda/.](https://console.aws.amazon.com/lambda/home ) No painel de navegação à esquerda, escolha **Funções**. 1. Selecione **Criar função**. 1. Configure os campos a seguir. + Nome da função: opensearch-function + Runtime: Python 3.9 + Arquitetura: x86\$164 Mantenha todas as outras opções padrão e escolha **Criar função**. 1. Na seção **Fonte do código** da página de resumo da função, escolha **Carregar** no menu suspenso e selecione **.zip. file**. Localize o arquivo `my-deployment-package.zip` que você criou e escolha **Salvar**. 1. O *manipulador* é o método no código da sua função que processa eventos. Em **Configurações do Runtime**, escolha **Editar** e altere o nome do manipulador de acordo com o nome do arquivo no pacote de implantação onde a função do Lambda está localizada Como seu arquivo se chama `opensearch-lambda.py`, renomeie o manipulador para `opensearch-lambda.lambda_handler`. Para saber mais, consulte [Manipulador de função do Lambda em Python](https://docs.aws.amazon.com/lambda/latest/dg/python-handler.html). ## Etapa 3: Criar a API no Gateway da API O uso do API Gateway permite criar uma API mais limitada e simplifica o processo de interação com a OpenSearch `_search` API. O API Gateway também permite ativar recursos de segurança, como a autenticação do Amazon Cognito e a limitação de solicitações. Execute as seguintes etapas para criar e implantar uma API: ### Criar e configurar a API Para criar sua API usando o console do API Gateway 1. Navegue até o console do API Gateway em [https://console.aws.amazon.com/apigateway/casa](https://console.aws.amazon.com/apigateway/home ). No painel de navegação esquerdo, escolha **APIs**. 1. Localize a **API REST** (não privada) e escolha **Compilar**. 1. Na página seguinte, localize a seção **Criar nova API** e verifique se a opção **Nova API** está selecionada. 1. Configure os campos a seguir. + Nome da API: **opensearch-api** + Descrição: **API pública para pesquisar um domínio do Amazon OpenSearch Service** + Tipo do endpoint: **Regional** 1. Selecione **Criar API**. 1. Escolha **Ações** e **Criar método**. 1. Select **GET** no menu suspenso e clique na marca de seleção para confirmar. 1. Defina as seguintes configurações e escolha **Salvar**: | Configuração | Valor | | --- | --- | | Tipo de integração | Função do Lambda | | Usar a integração de proxy do Lambda | Sim | | Região do Lambda | us-west-1 | | Função do Lambda | opensearch-lambda | | Usar o tempo limite padrão | Sim | ### Configurar a solicitação de método Escolha **Solicitação de métodot** e defina as seguintes configurações: | Configuração | Valor | | --- | --- | | Autorização | NONE | | Validador da solicitação | Validar parâmetros e cabeçalhos da string de consulta | | Chave da API necessária | false | Em **Parâmetros da string de consulta do URL)**, escolha **Adicionar string de consulta** e configure o seguinte parâmetro: | Configuração | Valor | | --- | --- | | Nome | q | | Obrigatório | Sim | ### Implante a API e configure um estágio O console do API Gateway permite que você implante uma API criando uma implantação e associando-a a um estágio novo ou existente. 1. Escolha **Ações** e **Implantar API**. 1. Para **Estágio da implantação)**, escolha **Novo estágio** e atribua o nome `opensearch-api-test` ao estágio. 1. Escolha **Implantar**. 1. Defina as seguintes configurações no editor de estágios e, em seguida, escolha **Salvar alterações**: | Configuração | Valor | | --- | --- | | Habilitar controle de utilização | Sim | | Taxa | 1000 | | Intermitência | 500 | Essas definições configuram uma API que possui apenas um método: uma solicitação `GET` para a raiz do endpoint (`https://some-id.execute-api.us-west-1.amazonaws.com/search-es-api-test`). A solicitação requer um único parâmetro (`q`), a string de consulta a ser pesquisada. Quando chamado, o método passa a solicitação para o Lambda, que executa a função `opensearch-lambda`. Para saber mais, consulte [Criação de uma API no Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-create-api.html) e [Implantação de uma API REST no Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-deploy-api.html). ## Etapa 4: (opcional) modificar a política de acesso ao domínio Seu domínio OpenSearch de serviço deve permitir que a função Lambda faça `GET` solicitações ao `movies` índice. Se o domínio tiver uma política de acesso aberto com controle de acesso refinado habilitado, você pode deixar como está: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "es:*", "Resource": "arn:aws:es:us-west-1:123456789012:domain/domain-name/*" } ] } ``` ------ Ou você pode escolher tornar a política de acesso ao domínio mais granular. Por exemplo, a política mínima a seguir fornece à `opensearch-lambda-role` (criada por meio do Lambda) acesso de leitura ao índice `movies`. Para obter o nome exato da função que o Lambda cria automaticamente, acesse o console AWS Identity and Access Management (IAM), escolha **Roles** e pesquise por “lambda”. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:role/service-role/opensearch-lambda-role-1abcdefg" }, "Action": "es:ESHttpGet", "Resource": "arn:aws:es:us-west-1:123456789012:domain/domain-name/movies/_search" } ] } ``` ------ **Importante** Se você tiver um controle de acesso refinado habilitado para o domínio, também precisará [mapear a função para um usuário](fgac.md#fgac-mapping) nos OpenSearch painéis, caso contrário, você verá erros de permissão. ### Configurar as permissões do perfil de execução do Lambda Além de configurar a política de acesso ao domínio, você também deve garantir que a função de execução do Lambda tenha as permissões de IAM necessárias para acessar OpenSearch seu domínio de serviço. A função Lambda requer permissões específicas, dependendo se você está usando um domínio gerenciado ou uma coleção OpenSearch Service Serverless. **Para domínios OpenSearch de serviço gerenciados:** Anexe a seguinte política do IAM à sua função de execução do Lambda para permitir que ela faça solicitações ao seu domínio de OpenSearch serviço: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "es:ESHttpGet", "es:ESHttpPost" ], "Resource": "arn:aws:es:us-west-1:123456789012:domain/domain-name/*" } ] } ``` ------ **Para coleções OpenSearch Service Serverless:** Se você estiver usando o OpenSearch Service Serverless, anexe a seguinte política do IAM à sua função de execução do Lambda: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "aoss:*", "Resource": "arn:aws:aoss:us-west-1:123456789012:collection/collection-id" } ] } ``` ------ Para anexar essas políticas ao perfil de execução do Lambda: 1. Navegue até o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Escolha **Perfis** e pesquise o perfil de execução do Lambda (normalmente denominado `opensearch-lambda-role-xxxxxxxx`). 1. Selecione **Adicionar permissões** e depois **Criar política em linha**. 1. Escolha a guia **JSON** e cole a política apropriada acima, substituindo os valores do espaço reservado pelo seu recurso real. ARNs 1. Escolha **Revisar política**, forneça um nome como `OpenSearchAccess` e escolha **Criar política**. **nota** Sem essas permissões do IAM, sua função Lambda receberá erros de “Acesso negado” ao tentar consultar seu domínio de OpenSearch serviço, mesmo que a política de acesso ao domínio permita as solicitações. Para saber mais sobre políticas de acesso, consulte [Configuração de políticas de acesso](createupdatedomains.md#createdomain-configure-access-policies). ## Mapeamento da função do Lambda (se estiver usando um controle de acesso minucioso) O controle de acesso minucioso introduz uma etapa adicional antes de testar a aplicação. Mesmo se você usar a autenticação básica do HTTP para todos os outros fins, será necessário mapear a função do Lambda para um usuário. Caso contrário, você receberá erros de permissões. 1. Navegue até o URL dos OpenSearch painéis do domínio. 1. No menu principal, escolha **Segurança**, **Funções** e selecione o link para `all_access`, a função para a qual precisa mapear a função do Lambda. 1. Escolha **Usuários mapeados** e **Gerenciar mapeamento**. 1. Em **Funções de backend**, adicione o nome do recurso da Amazon (ARN) da função do Lambda. O ARN deve assumir a forma de `arn:aws:iam::123456789123:role/service-role/opensearch-lambda-role-1abcdefg`. 1. Selecione **Mapa** e confirme se o usuário ou função aparece em **Usuários mapeados**. ## Etapa 5: Testar a aplicação Web **Para testar o aplicativo web** 1. Faça download do [sample-site.zip](samples/sample-site.zip), descompacte-o e abra `scripts/search.js` em seu editor de texto de preferência. 1. Atualize a variável `apigatewayendpoint` para apontar para o endpoint do API Gateway Você pode encontrar rapidamente o endpoint no API Gateway escolhendo **Estágios** e selecionando o nome da API. A variável `apigatewayendpoint` deve assumir a forma de `https://some-id.execute-api.us-west-1.amazonaws.com/opensearch-api-test`. 1. Abra `index.html` e tente executar pesquisas para *thor*, *casa* e alguns outros termos. ![\[Um exemplo de pesquisa por thor.\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/images/search-ui.png) ### Solucionar erros CORS Mesmo que a função do Lambda inclua conteúdo na resposta para ser compatível com o CORS, você ainda pode ver o seguinte erro: ``` Access to XMLHttpRequest at '' from origin 'null' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present in the requested resource. ``` Se isso acontecer, tente o seguinte: 1. [Habilite o CORS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-cors-console.html) no recurso GET. Em **Avançado**, defina **Access-Control-Allow-Credentials** como `'true'`. 1. Reimplante a API no API Gateway [**Ações**, **Implantar API**]. 1. Exclua e torne a adicionar o acionador da função do Lambda. Adicione readicionar, escolha **Adicionar acionador** e crie o endpoint HTTP que invoca sua função. O acionador deve ter a seguinte configuração: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/opensearch-service/latest/developerguide/search-example.html) ## Próximas etapas Este capítulo é apenas um ponto de partida para demonstrar um conceito. Você pode considerar as seguintes modificações: + Adicione seus próprios dados ao domínio do OpenSearch Serviço. + Adicionar métodos à API. + Na função do Lambda, modifique a consulta de pesquisa ou incremente campos diferentes. + Estilize os resultados de maneira diferente ou modifique `search.js` para exibir campos diferentes para o usuário.