Compartir vía

Inicio rápido: Búsqueda de palabras clave mediante REST

  • Artículo

Las API de REST de Búsqueda de Azure AI proporcionan acceso mediante programación a todas sus funcionalidades, incluidas las características en vista previa, y son una manera fácil de aprender cómo funcionan las características. En este inicio rápido, aprenderá a llamar a las API de REST de Búsqueda para crear, cargar y consultar un índice de búsqueda en Búsqueda de Azure AI.

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

Requisitos previos

Descarga de archivos

Descargue un ejemplo de REST de GitHub para enviar las solicitudes de este inicio rápido. Puede encontrar instrucciones en Descarga de archivos desde GitHub.

También puede iniciar un nuevo archivo en el sistema local y crear solicitudes manualmente con las instrucciones de este artículo.

Obtención de un punto de conexión de servicio de búsqueda

Puede encontrar el punto de conexión del servicio de búsqueda en Azure Portal.

  1. Inicie sesión en Azure Portal y encuentre su servicio de búsqueda.

  2. En la página principal Información general, busque la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.

    Captura de pantalla de la propiedad URL en la página de información general.

Va a pegar este punto de conexión en el archivo .rest o .http en un paso posterior.

Configurar el acceso

Las solicitudes al punto de conexión de búsqueda deben autenticarse y autorizarse. Puede usar claves de API o roles para esta tarea. Las claves son más fáciles de empezar, pero los roles son más seguros.

Para una conexión basada en roles, las instrucciones siguientes le indican que se conecta a Azure AI Search en su identidad, no la identidad de una aplicación cliente.

Opción 1: Usar claves

Seleccione Configuración>Claves y luego copie una clave de administrador. Las claves de administrador se utilizan para agregar, modificar y eliminar objetos. Hay dos claves de administrador intercambiables. Copie una de las dos. Para saber más, consulte Conexión a Azure AI Search mediante la autenticación de claves.

Captura de pantalla que muestra las claves de API en Azure Portal.

Va a pegar esta clave en el archivo .rest o .http en un paso posterior.

Opción 2: Usar roles

Asegúrese de que el servicio de búsqueda está configurado para el acceso basado en roles. Debe tener asignaciones de roles preconfiguradas para el acceso para desarrolladores. Las asignaciones de roles deben conceder permiso para crear, cargar y consultar un índice de búsqueda.

En esta sección, obtenga el token de identidad personal mediante la CLI de Azure, Azure PowerShell o Azure Portal.

  1. Inicie sesión en la CLI de Azure.

    az login

  2. Obtenga su token de identidad personal.

    az account get-access-token --scope https://search.azure.com/.default

Va a pegar el token de identidad personal en el archivo .rest o .http en un paso posterior.

Nota:

En esta sección se da por supuesto que usa un cliente local que se conecta a Azure AI Search en su nombre. Un enfoque alternativo consiste en obtener un token para la aplicación cliente, suponiendo que la aplicación está registrada con Microsoft Entra ID.

Configurar Visual Studio Code

Si no está familiarizado con el cliente REST para Visual Studio Code, esta sección incluye la configuración para que pueda completar las tareas de este inicio rápido.

  1. Inicie Visual Studio Code y seleccione el icono Extensiones.

  2. Busque el cliente REST y seleccione Instalar.

    Captura de pantalla que muestra el botón Instalar del cliente REST.

  3. Abra o cree un nuevo archivo denominado con una extensión de archivo .rest o .http.

  4. Pegue el ejemplo siguiente si usa claves de API. Reemplace los marcadores de posición @baseUrl y @apiKey por los valores que copió anteriormente, sin comillas.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. O bien, pegue este ejemplo si usa roles. Reemplace los marcadores de posición @baseUrl y @token por los valores que copió anteriormente, sin comillas.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  6. Seleccione Enviar solicitud. Debe aparecer una respuesta en un panel adyacente. Si tiene índices existentes, se muestran. En caso contrario, la lista está vacía. Si el código HTTP es 200 OK, estará listo para los pasos siguientes.

    Captura de pantalla que muestra un cliente REST configurado para una solicitud de servicio de búsqueda.

    Si obtiene WWW-Authenticate: Bearer realm="Azure Cognitive Search" error="invalid_token" error_description="Authentication token failed validation.", quite las comillas alrededor del token, guarde el archivo y vuelva a intentar la solicitud.

    Puntos clave:

    • Los parámetros se especifican mediante un prefijo @.
    • ### designa una llamada REST. La siguiente línea contiene la solicitud, que debe incluir HTTP/1.1.
    • Send request debe aparecer encima de la solicitud.

Creación de un índice

Agregue una segunda solicitud al archivo .rest. Crear índice (REST) crea un índice de búsqueda y configura las estructuras de datos físicas en el servicio de búsqueda.

  1. Pegue el siguiente ejemplo para crear el índice hotels-quickstart en el servicio de búsqueda.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "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}
                ]
            }
        ]
    }

  2. Seleccione Enviar solicitud. Debe tener una respuesta HTTP/1.1 201 Created y el cuerpo de la respuesta debe incluir la representación JSON del esquema de índice.

    Si recibe un error Header name must be a valid HTTP token ["{"], asegúrese de que hay una línea vacía entre el api-key y el cuerpo de la solicitud. Si obtiene HTTP 504, compruebe que la URL especifica HTTPS. Si se muestra el error HTTP 400 o 404, compruebe el cuerpo de la solicitud para verificar que no haya errores al copiar/pegar. Un HTTP 403 suele indicar un problema con la clave de API. Es una clave no válida o un problema de sintaxis con la forma en que se especifica la clave de API.

    Ahora tiene varias solicitudes en el archivo. Recuerde que ### inicia una nueva solicitud y cada solicitud se ejecuta de forma independiente.

    Captura de pantalla que muestra el cliente REST con varias solicitudes.

Acerca de la definición del índice

Dentro del esquema de índice, la colección de campos define la estructura del documento. Cada documento que cargue debe tener estos campos. Cada campo debe asignarse a un tipo de datos Entity Data Model (EDM). Los campos de cadena se usan en la búsqueda de texto completo. Si desea que se puedan buscar datos numéricos, asegúrese de que el tipo de datos sea Edm.String. Otros tipos de datos, como Edm.Int32, se pueden filtrar, ordenar, configurar y recuperar, pero no admiten la búsqueda de texto completo.

Los atributos del campo determinan las acciones que se permiten. Las API de REST permiten muchas acciones de forma predeterminada. Por ejemplo, todas las cadenas se pueden buscar y recuperar de forma predeterminada. En el caso de las API de REST, es posible que solo tenga que atributos si necesita desactivar un comportamiento.

{
    "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}
        ]
     }
  ]
}

Carga de documentos

La creación y la carga del índice son pasos independientes. En Búsqueda de Azure AI, el índice contiene todos los datos que se pueden buscar y las consultas se ejecutan en el servicio de búsqueda. En las llamadas de REST, los datos se proporcionan como documentos JSON. Use Documentación: Index REST API para esta tarea.

El URI se extiende para que incluya las colecciones de docs y la operación index.

  1. Pegue el siguiente ejemplo para cargar documentos JSON en el índice de búsqueda.

    ### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "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"
            }
        }
      ]
    }

  2. Seleccione Enviar solicitud. En unos segundos, debería ver una respuesta HTTP 201 en el panel adyacente.

    Si obtiene un 207, al menos un documento no pudo cargarse. Si obtiene un error 404, se ha producido un error de sintaxis en el encabezado o en el cuerpo de la solicitud. Compruebe que ha cambiado el punto de conexión para incluir /docs/index.

Ejecutar consultas

Ahora que se han cargado los documentos, puede emitir consultas en ellos mediante Documentación: Search Post (REST).

El URI se extiende para incluir una expresión de consulta, especificada mediante el operador /docs/search.

  1. Pegue el siguiente ejemplo para consultar el índice de búsqueda. Luego, seleccione Enviar solicitud. Una solicitud de búsqueda de texto siempre incluye un parámetro search. En este ejemplo se incluye un parámetro opcional searchFields que restringe la búsqueda de texto a campos específicos.

    ### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
      "search": "lake view",
      "select": "HotelId, HotelName, Tags, Description",
      "searchFields": "Description, Tags",
      "count": true
  }

  2. Revise la respuesta en el panel adyacente. Debe tener un recuento que indique el número de coincidencias encontradas en el índice, una puntuación de búsqueda que indique relevancia y valores para cada campo enumerado en la instrucción select.

    {
  "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)",
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.6189728,
      "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.",
      "Tags": [
        "concierge",
        "view",
        "24-hour front desk service"
      ]
    }
  ]
}

Obtención de las propiedades del índice

También puede usar Obtener estadísticas para consultar los recuentos de documentos y el tamaño del índice.

  1. Pegue el siguiente ejemplo para consultar el índice de búsqueda. Luego, seleccione Enviar solicitud.

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  2. Revise la respuesta. Esta operación es una manera fácil de obtener detalles sobre el almacenamiento de índices.

    {
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

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 bien eliminar el grupo de recursos para eliminar todo el conjunto de recursos.

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

También puede probar este comando DELETE:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Paso siguiente

Ahora que está familiarizado con el cliente REST y realiza llamadas REST a Búsqueda de Azure AI, pruebe otro inicio rápido que muestre la compatibilidad con vectores.

Inicio rápido: vector de búsqueda mediante REST