Inicio rápido: Creación de un índice de búsqueda en PowerShell mediante API de REST

Artículo
03/29/2024

En este inicio rápido de Búsqueda de Azure AI, aprenderá a crear, cargar y consultar un índice de búsqueda mediante PowerShell y las API de REST de Búsqueda de Azure AI. En el artículo se explica cómo se ejecutan los comandos de PowerShell de forma interactiva. También puede descargar y ejecutar un script de PowerShell que realice las mismas operaciones.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Requisitos previos

Los siguientes servicios y herramientas son necesarios para este inicio rápido:

PowerShell 7.3 o una versión posterior mediante Invoke-RestMethod para los pasos secuenciales e interactivos.
Cree un servicio de Azure AI Search o busque un servicio existente en su suscripción actual. Puede usar un servicio gratuito para este inicio rápido.

Copiar una clave y una dirección URL del servicio de búsqueda

En este inicio rápido, las llamadas REST incluyen la dirección URL del servicio y una clave de acceso en cada solicitud. Con ambos se crea un servicio de búsqueda, por lo que si ha agregado Búsqueda de Azure AI a su suscripción, siga estos pasos para obtener la información necesaria.

Inicie sesión en Azure Portal. En la página Información general del servicio de búsqueda, obtenga la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.
Seleccione Configuración>Claves y, a continuación, obtenga una clave de administrador para obtener derechos completos en el servicio. Se proporcionan dos claves de administración intercambiables para la continuidad empresarial si necesita revertir una. Puede usar la clave principal o secundaria en las solicitudes para agregar, modificar y eliminar objetos.

Todas las solicitudes requieren una clave de API en cada solicitud enviada al servicio. Tener una clave válida genera la confianza, solicitud a solicitud, entre la aplicación que envía la solicitud y el servicio que se encarga de ella.

Conexión a Azure AI Search

En PowerShell, cree un objeto $headers para almacenar el tipo de contenido y la clave API. Reemplace la clave API de administración (YOUR-ADMIN-API-KEY) por una clave válida para el servicio de búsqueda. Solo tiene que establecer este encabezado una vez durante la sesión, pero lo agregará a cada solicitud.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Cree un objeto $url que especifique la colección de índices del servicio. Reemplace el nombre del servicio (YOUR-SEARCH-SERVICE-NAME) por un servicio de búsqueda válido.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Ejecute Invoke-RestMethod para enviar una solicitud GET al servicio y comprobar la conexión. Agregue ConvertTo-Json para poder ver las respuestas que se envían desde el servicio.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Si el servicio está vacío y no tiene índices, los resultados son similares al ejemplo siguiente. De lo contrario, verá una representación JSON de definiciones de índice.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Creación de un índice

A menos que use el portal, debe existir un índice en el servicio para poder cargar datos. En este paso se define el índice y se inserta en el servicio. Para este paso se usa la API REST Create Index.

Los elementos necesarios de un índice incluyen un nombre y una colección de campos. La colección de campos define la estructura de un documento. Cada campo tiene un nombre, un tipo y atributos que determinan cómo se usa (por ejemplo, si es de texto completo que se puede buscar, filtrar o recuperar en los resultados de búsqueda). Dentro de un índice, uno de los campos de tipo Edm.String se debe designar como la clave para la identidad del documento.

Este índice se denomina hotels-quickstart y tiene las definiciones de campo que ve en el siguiente código. Es un subconjunto de un índice de hoteles mayor usado en otros artículos. Las definiciones de campo se recortan en este inicio rápido para mayor brevedad.

Pegue este ejemplo en PowerShell para crear un objeto $body que contenga el 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}
        ]
     }
  ]
}
"@

Establezca el URI en la colección de índices del servicio y el índice hotels-quickstart.

$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"

Ejecute el comando con $url, $headers y $body para crear el índice en el servicio.

Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json

Los resultados deben tener un aspecto similar a este ejemplo, que muestra solo los dos primeros campos para mayor brevedad:

{
    "@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":  ""
                },
                . . .
    ]
}

Sugerencia

Para realizar una comprobación, también puede consultar la lista Índices en el portal.

Carga de documentos

Para insertar documentos, use una solicitud HTTP POST al punto de conexión de la dirección URL del índice. La API REST de esta tarea es Add, Update, or Delete Documents.

Pegue este ejemplo en PowerShell para crear un objeto $body que contenga los documentos que desea cargar.

Esta solicitud incluye dos registros completos y un registro parcial. El registro parcial indica que puede cargar documentos incompletos. El parámetro @search.action especifica cómo se realiza la indexación. Los valores válidos son upload, merge, mergeOrUploady delete. El comportamiento mergeOrUpload crea un nuevo documento para hotelId = 3 o actualiza el contenido si ya existe.

$body = @"
{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1",
    "HotelName": "Secret Point Motel",
    "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": "Twin Dome Motel",
    "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": "Triple 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 Cliff Hotel",
    "Description": "Sublime Cliff 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 Cliff 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"
        }
    }
]
}
"@

Establezca el punto de conexión en la colección de documentos hotels-quickstart e incluya la operación de índice (indexes/hotels-quickstart/docs/index).
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

Ejecute el comando con $url, $headers y $body para cargar documentos en el índice hotels-quickstart.

Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json

Los resultados deben tener un aspecto similar al siguiente ejemplo. Debería ver un código de estado 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
                }
            ]
}

Búsqueda de un índice

En este paso se muestra cómo consultar un índice mediante la API de búsqueda en documentos.

Asegúrese de usar comillas simples en la búsqueda $urls. Las cadenas de consulta incluyen caracteres $ y se puede omitir el uso de una secuencia de escape si toda la cadena está entre comillas simples.

Establezca el punto de conexión en la colección de documentos hotels-quickstart y agregue un parámetro search para pasarlo una cadena de consulta.

Esta cadena ejecuta una búsqueda vacía (search=*), que devuelve una lista no clasificada (puntuación de búsqueda = 1,0) de documentos arbitrarios. De forma predeterminada, Azure AI Search devuelve 50 resultados cada vez. Al ser estructurada, esta consulta devuelve la estructura y los valores del documento entero. Agregue $count=true para obtener un recuento de todos los documentos de los resultados.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

Ejecute el comando para enviar el $url al servicio.

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Los resultados deben tener un aspecto similar a la siguiente salida:

{
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "HotelId":  "2",
                  "HotelName":  "Twin Dome Motel",
                  "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":  "Triple 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}"
              },
            . . .
    ]
}

Pruebe con algunos otros ejemplos de consultas para hacerse una idea de la sintaxis. Puede efectuar una búsqueda de cadena, realizar consultas $filter textuales, limitar el conjunto de resultados, definir el ámbito de la búsqueda a campos específicos, etc.

# 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=2023-11-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=2023-11-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=2023-11-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=2023-11-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

Limpieza de recursos

Cuando trabaje con su propia suscripción, es una buena idea al final de un proyecto identificar si todavía se necesitan los recursos que ha creado. Los recursos que se dejan en ejecución pueden costarle mucho dinero. Puede eliminar los recursos de forma individual o eliminar el grupo de recursos para eliminar todo el conjunto de recursos.

Puede encontrar y administrar recursos en el portal mediante el vínculo Todos los recursos o Grupos de recursos en el panel izquierdo.

Si está usando un servicio gratuito, recuerde que está limitado a tres índices, indexadores y orígenes de datos. Puede eliminar elementos individuales en el portal para mantenerse por debajo del límite.

Pasos siguientes

En este tutorial, has usado PowerShell para llevar a cabo los pasos del flujo de trabajo básico para crear contenido y acceder a él en Azure AI Search. Teniendo en cuenta los conceptos, se recomienda pasar a escenarios más avanzados, como la indexación de orígenes de datos de Azure:

Tutorial de REST: Indexar y buscar datos semiestructurados (blobs JSON) en Búsqueda de Azure AI