Inicio rápido: búsqueda de texto 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. Para obtener más información, consulte Descarga de archivos de GitHub.

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

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

Las llamadas de REST requieren el punto de conexión de servicio de búsqueda y una clave de API en cada solicitud. Puede obtener estos valores en Azure Portal.

  1. Inicie sesión en Azure Portal. Luego, vaya al servicio de búsqueda de la página de información general y copie la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://mydemo.search.windows.net.

  2. 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.

    Captura de pantalla que muestra la dirección URL y las claves de API en Azure Portal.

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. Reemplace la dirección URL base y la clave de API por los valores que copió anteriormente.

    @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=2023-11-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. 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.

    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=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "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=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

  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=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "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 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.",
      "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=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

  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 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.

También puede probar este comando DELETE:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-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