Administración del servicio de Búsqueda de Azure AI mediante las API REST

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Aprenda a crear y configurar un servicio de Búsqueda de Azure AI mediante las API REST de Management. Solo se garantiza que las API rest de administración proporcionen acceso anticipado a las características en versión preliminar.

La API REST de administración está disponible en versiones estables y en versión preliminar. Asegúrese de establecer una versión preliminar de la API si tiene acceso a las características en versión preliminar.

Todas las API rest de administración tienen ejemplos. Si una tarea no se trata en este artículo, consulte la referencia de API en su lugar.

Sugerencia

Si usa CURL para llamar a la API REST de gestión, asegúrese de establecer el encabezado de tipo de contenido como application/json: -H "Content-Type: application/json". Como alternativa, puede usar la --JSON marca si desea insertar el JSON.

Requisitos previos

  • Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

  • Visual Studio Code con un cliente REST.

  • CLI de Azure para obtener un token de acceso, como se describe en los pasos siguientes. Debe ser propietario o administrador en la suscripción de Azure.

    Las llamadas a la API REST de administración se autentican mediante Microsoft Entra ID. Debe proporcionar un token de acceso en la solicitud y los permisos para crear y configurar un recurso. Además del CLI de Azure, puede usar Azure PowerShell para crear un token de acceso.

    1. Abra un shell de comandos para CLI de Azure.

    2. Inicie sesión en la suscripción de Azure. Si tiene varios inquilinos o suscripciones, asegúrese de seleccionar el correcto.

      az login

    3. Obtenga el identificador de inquilino y el identificador de suscripción.

      az account show

    4. Obtenga un token de acceso.

      az account get-access-token --query accessToken --output tsv

      Debe tener un identificador de inquilino, un identificador de suscripción y un token de portador. Pegará estos valores en el archivo .rest o .http que cree en el paso siguiente.

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 artículo.

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

  2. Busque el cliente REST y seleccione Instalar.

    Captura de pantalla del comando install.

  3. Abra o cree un nuevo archivo que tenga la extensión de archivo .rest o .http.

  4. Proporcione variables para los valores que recuperó en el paso anterior.

    @tenant-id = PUT-YOUR-TENANT-ID-HERE
@subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
@token = PUT-YOUR-TOKEN-HERE

  5. Compruebe que la sesión está operativa enumerando los servicios de búsqueda de la suscripción.

     ### List search services
 GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
      Content-type: application/json
      Authorization: Bearer {{token}}

  6. Seleccione Enviar solicitud. Una respuesta debe aparecer en un panel adyacente. Si tiene servicios de búsqueda existentes, estos se muestran. De lo contrario, la lista está vacía, pero siempre que el código HTTP sea 200 OK, estará listo para los pasos siguientes.

    HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

Creación o actualización de un servicio

Crea o actualiza un servicio de búsqueda en la suscripción actual. En este ejemplo se usan variables para el nombre y la región del servicio de búsqueda, que aún no se han definido. Proporcione los nombres directamente o agregue nuevas variables a la colección.

### Create a search service (provide an existing resource group)
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

Actualización de un servicio

Algunas funcionalidades de Búsqueda de Azure AI solo están disponibles para los nuevos servicios. Para evitar la recreación del servicio y llevar estas funcionalidades a un servicio existente, es posible que pueda actualizar el servicio.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Cambiar niveles de precios

Si necesita más o menos capacidad, puede cambiar a otro plan de tarifa. Actualmente, solo puede cambiar entre los niveles Básico y Estándar (S1, S2 y S3). Use la sku propiedad para especificar el nuevo nivel.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Creación de un servicio S3HD

Para crear un servicio S3HD , use una combinación de sku propiedades y hostingMode . Establezca sku en standard3 y "hostingMode" en HighDensity.

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Configuración del acceso basado en roles para el plano de datos

Se aplica a: Colaborador de datos de índice de búsqueda, Lector de datos de índice de búsqueda, Colaborador del servicio de búsqueda

Configure el servicio de búsqueda para reconocer un encabezado de autorización en las solicitudes de datos que proporcionan un token de acceso de OAuth2.

Para usar el control de acceso basado en roles para las operaciones del plano de datos, establezca authOptions a aadOrApiKey y luego envíe la solicitud.

Para usar el control de acceso basado en rol exclusivamente, desactive la autenticación de clave de API siguiendo una segunda solicitud, esta vez se establece disableLocalAuth en true.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Configuración de la computación confidencial

La computación confidencial es un tipo de proceso opcional para la protección de datos en uso. Cuando se configura, el servicio de búsqueda se implementa en máquinas virtuales confidenciales (DCasv5 o DCesv5) en lugar de máquinas virtuales estándar. Este tipo de proceso también incurre en un recargo del 10 % por los niveles facturables. Para obtener más información, consulte la página de precios.

Para el uso diario, la computación confidencial no es necesaria. Sólo se recomienda este tipo de computación para estrictos requisitos normativos, de cumplimiento o de seguridad. Para más información, consulte Casos de uso de computación confidencial.

El tipo de computación se fija a lo largo de la vida de su servicio de búsqueda. Para configurar de forma permanente la informática confidencial, establezca la propiedad computeType en confidential en un nuevo servicio.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

Aplicar una directiva de clave administrada por el cliente

Si está utilizando cifrado administrado por el cliente, puede habilitar "encryptionWithCMK" con "enforcement" configurado como "Enabled" si desea que el servicio de búsqueda informe su estado de cumplimiento.

Al habilitar esta directiva, se producirá un error en las llamadas REST que creen objetos que contengan datos confidenciales, como el cadena de conexión dentro de un origen de datos, si no se proporciona una clave de cifrado: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Deshabilitar tareas que envían datos a recursos externos

Búsqueda de Azure AI escribe en orígenes de datos externos al actualizar un almacén de conocimiento, guardar el estado de sesión de depuración o almacenar en caché enriquecimientos. En el ejemplo siguiente se deshabilitan estas cargas de trabajo en el nivel de servicio.

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Eliminación de un servicio de búsqueda

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Enumeración de claves de API de administración

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Regeneración de claves de API de administración

Solo puede volver a generar una clave de API de administrador a la vez.

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Creación de claves de API de consulta

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Enumeración de conexiones de punto de conexión privado

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Enumerar operaciones de búsqueda

### List search operations
GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups?api-version=2021-04-01  HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Pasos siguientes

Una vez configurado un servicio de búsqueda, los pasos siguientes incluyen crear un índice o consulta un índice mediante el portal de Azure, las API REST o un SDK de Azure.

  • Last updated on