Guia de início rápido: criar um índice de pesquisa no PowerShell usando APIs REST
Neste início rápido do Azure AI Search, saiba como criar, carregar e consultar um índice de pesquisa usando o PowerShell e as APIs REST do Azure AI Search. Este artigo explica como executar comandos do PowerShell interativamente. Como alternativa, você pode baixar e executar um script do PowerShell que executa as mesmas operações.
Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Pré-requisitos
Os seguintes serviços e ferramentas são necessários para este início rápido:
- PowerShell 7.3 ou posterior, usando Invoke-RestMethod para etapas sequenciais e interativas.
- Crie um serviço Azure AI Search ou localize um serviço existente na sua subscrição atual. Você pode usar um serviço gratuito para este início rápido.
Copiar uma chave de serviço de pesquisa e URL
Neste início rápido, as chamadas REST incluem a URL do serviço e uma chave de acesso em cada solicitação. Um serviço de pesquisa é criado com ambos, portanto, se você adicionou o Azure AI Search à sua assinatura, siga estas etapas para obter as informações necessárias.
Inicie sessão no portal do Azure. Na página Visão geral do serviço de pesquisa, obtenha o URL. Um ponto final de exemplo poderá ser parecido com
https://mydemo.search.windows.net.Selecione Configurações>Chaves e, em seguida, obtenha uma chave de administrador para obter direitos totais no serviço. Duas chaves de administração intercambiáveis são fornecidas para continuidade de negócios se você precisar rolar uma. Você pode usar a chave primária ou secundária em solicitações para adicionar, modificar e excluir objetos.
Todas as solicitações exigem uma chave de API em cada solicitação enviada ao seu serviço. Ter uma chave válida estabelece confiança, por solicitação, entre o aplicativo que envia a solicitação e o serviço que a manipula.
Conectar-se à Pesquisa de IA do Azure
No PowerShell, crie um
$headersobjeto para armazenar o tipo de conteúdo e a chave da API. Substitua a chave da API admin (YOUR-ADMIN-API-KEY) por uma chave válida para o seu serviço de pesquisa. Você só precisa definir esse cabeçalho uma vez durante a sessão, mas adicioná-lo a todas as solicitações.$headers = @{ 'api-key' = '<YOUR-ADMIN-API-KEY>' 'Content-Type' = 'application/json' 'Accept' = 'application/json' }Crie um
$urlobjeto que especifique a coleção de índices do serviço. Substitua o nome do serviço (YOUR-SEARCH-SERVICE-NAME) por um serviço de pesquisa válido.$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2024-07-01&`$select=name"Execute
Invoke-RestMethodpara enviar uma solicitação GET para o serviço e verifique a conexão. AdicioneConvertTo-Jsonpara que você possa visualizar as respostas enviadas de volta do serviço.Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-JsonSe o serviço estiver vazio e não tiver índices, os resultados serão semelhantes ao exemplo a seguir. Caso contrário, você verá uma representação JSON de definições de índice.
{ "@odata.context": "https://mydemo.search.windows.net/$metadata#indexes", "value": [ ] }
Criar um índice
A menos que você esteja usando o portal do Azure, um índice deve existir no serviço antes de carregar dados. Esta etapa define o índice e o envia para o serviço. A API REST de criação de índice é usada para esta etapa.
Os elementos necessários de um índice incluem um nome e uma coleção de campos. A coleção fields define a estrutura de um documento. Cada campo tem um nome, tipo e atributos que determinam como ele é usado (por exemplo, se é pesquisável em texto completo, filtrável ou recuperável nos resultados da pesquisa). Dentro de um índice, um dos campos do tipo Edm.String deve ser designado como a chave para a identidade do documento.
Esse índice é nomeado hotels-quickstart e tem as definições de campo que você vê no código a seguir. É um subconjunto de um índice de hotéis maior usado em outros artigos passo a passo. As definições de campo são cortadas neste guia de início rápido para maior brevidade.
Cole este exemplo no PowerShell para criar um
$bodyobjeto que contenha o esquema de índice.$body = @" { "name": "hotels-quickstart", "fields": [ {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true}, {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false}, {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"}, {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true}, {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true}, {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true}, {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true}, {"name": "Address", "type": "Edm.ComplexType", "fields": [ {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true}, {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}, {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true} ] } ] } "@Defina o URI como a coleção de índices em seu serviço e o
hotels-quickstartíndice.$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2024-07-01"Execute o comando com
$url,$headerse$bodypara criar o índice no serviço.Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-JsonOs resultados devem ser semelhantes a este exemplo, que mostra apenas os dois primeiros campos para brevidade:
{ "@odata.context": "https://mydemo.search.windows.net/$metadata#indexes/$entity", "@odata.etag": "\"0x8D6EDE28CFEABDA\"", "name": "hotels-quickstart", "defaultScoringProfile": null, "fields": [ { "name": "HotelId", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "sortable": true, "facetable": true, "key": true, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": null, "synonymMaps": "" }, { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "sortable": true, "facetable": false, "key": false, "indexAnalyzer": null, "searchAnalyzer": null, "analyzer": null, "synonymMaps": "" }, . . . ] }
Gorjeta
Para verificação, você também pode verificar a lista Índices no portal do Azure.
Carregar documentos
Para enviar documentos por push, use uma solicitação HTTP POST para o ponto de extremidade de URL do índice. A API REST para esta tarefa é Documentos de Índice.
Cole este exemplo no PowerShell para criar um
$bodyobjeto que contenha os documentos que você deseja carregar.Este pedido inclui dois registos completos e um registo parcial. O registo parcial demonstra que pode carregar documentos incompletos. O
@search.actionparâmetro especifica como a indexação é feita. Os valores válidos incluemupload,merge,mergeOrUploadedelete. OmergeOrUploadcomportamento cria um novo documento ouhotelId = 3atualiza o conteúdo, se ele já existir.$body = @" { "value": [ { "@search.action": "upload", "HotelId": "1", "HotelName": "Stay-Kay City Hotel", "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.", "Category": "Boutique", "Tags": [ "pool", "air conditioning", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1970-01-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "677 5th Ave", "City": "New York", "StateProvince": "NY", "PostalCode": "10022", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "2", "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": [ "pool", "free wifi", "concierge" ], "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.60, "Address": { "StreetAddress": "140 University Town Center Dr", "City": "Sarasota", "StateProvince": "FL", "PostalCode": "34243", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "3", "HotelName": "Gastronomic Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.", "Category": "Resort and Spa", "Tags": [ "air conditioning", "bar", "continental breakfast" ], "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.80, "Address": { "StreetAddress": "3393 Peachtree Rd", "City": "Atlanta", "StateProvince": "GA", "PostalCode": "30326", "Country": "USA" } }, { "@search.action": "upload", "HotelId": "4", "HotelName": "Sublime Palace Hotel", "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Palace is part of a lovingly restored 1800 palace.", "Category": "Boutique", "Tags": [ "concierge", "view", "24-hour front desk service" ], "ParkingIncluded": true, "LastRenovationDate": "1960-02-06T00:00:00Z", "Rating": 4.60, "Address": { "StreetAddress": "7400 San Pedro Ave", "City": "San Antonio", "StateProvince": "TX", "PostalCode": "78216", "Country": "USA" } } ] } "@Defina o ponto de extremidade para a
hotels-quickstartcoleção de documentos e inclua a operação de índice (indexes/hotels-quickstart/docs/index).$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2024-07-01"Execute o comando com
$url,$headerse$bodypara carregar documentos nohotels-quickstartíndice.Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-JsonOs resultados devem ser semelhantes ao exemplo a seguir. Você verá um código de status de 201.
{ "@odata.context": "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)", "value": [ { "key": "1", "status": true, "errorMessage": null, "statusCode": 201 }, { "key": "2", "status": true, "errorMessage": null, "statusCode": 201 }, { "key": "3", "status": true, "errorMessage": null, "statusCode": 201 }, { "key": "4", "status": true, "errorMessage": null, "statusCode": 201 } ] }
Pesquisar um índice
Esta etapa mostra como consultar um índice usando a API de Documentos de Pesquisa.
Certifique-se de usar aspas simples na pesquisa $urls. As cadeias de caracteres de consulta incluem $ caracteres e você pode omitir a necessidade de escapar deles se toda a cadeia de caracteres estiver entre aspas simples.
Defina o ponto de extremidade para a
hotels-quickstartcoleção docs e adicione umsearchparâmetro para passar em uma cadeia de caracteres de consulta.Esta cadeia de caracteres executa uma pesquisa vazia (
search=*), retornando uma lista não classificada (pontuação de pesquisa = 1,0) de documentos arbitrários. Por padrão, o Azure AI Search retorna 50 correspondências de cada vez. Conforme estruturada, essa consulta retorna uma estrutura e valores de documento inteiros. Adicionar$count=truepara obter uma contagem de todos os documentos nos resultados.$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=*&$count=true'Execute o comando para enviar o
$urlpara o serviço.Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-JsonOs resultados devem ser semelhantes aos seguintes resultados:
{ "@odata.context": "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)", "@odata.count": 4, "value": [ { "@search.score": 0.1547872, "HotelId": "2", "HotelName": "Old Century Hotel", "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.", "Category": "Boutique", "Tags": "pool free wifi concierge", "ParkingIncluded": false, "LastRenovationDate": "1979-02-18T00:00:00Z", "Rating": 3.6, "Address": "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}" }, { "@search.score": 0.009068266, "HotelId": "3", "HotelName": "Gastronomic Landscape Hotel", "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel\u0027s restaurant services.", "Category": "Resort and Spa", "Tags": "air conditioning bar continental breakfast", "ParkingIncluded": true, "LastRenovationDate": "2015-09-20T00:00:00Z", "Rating": 4.8, "Address": "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}" }, . . . ] }
Experimente alguns outros exemplos de consulta para ter uma ideia da sintaxe. Você pode fazer uma pesquisa de cadeia de caracteres, consultas literais $filter , limitar o conjunto de resultados, definir o escopo da pesquisa para campos específicos e muito mais.
# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'
# Query example 2
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'
# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=boutique&$top=2&$select=HotelName,Category'
# Query example 4
# Sort by a specific field (Address/City) in ascending order
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2024-07-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'
Clean up resources (Limpar recursos)
Ao trabalhar na sua própria subscrição, recomendamos que verifique, depois de concluir um projeto, se ainda vai precisar dos recursos que criou. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.
Você pode localizar e gerenciar recursos no portal do Azure usando o link Todos os recursos ou Grupos de recursos no painel mais à esquerda.
Se você estiver usando um serviço gratuito, lembre-se de que está limitado a três índices, indexadores e fontes de dados. Você pode excluir itens individuais no portal do Azure para permanecer abaixo do limite.
Próximos passos
Neste início rápido, você usou o PowerShell para percorrer o fluxo de trabalho básico para criar e acessar conteúdo no Azure AI Search. Com os conceitos em mente, recomendamos que você passe para cenários mais avançados, como a indexação de fontes de dados do Azure: