Administrar el servicio de Azure AI Search con las API de REST

Artículo
12/10/2024

En este artículo se enseña a crear y configurar un servicio de Azure AI Search mediante las API de REST de administración. Solo se garantiza que las API REST de administración proporcionen acceso anticipado a las características en versión preliminar.

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

Creación o actualización de un secreto
Habilitar el control de acceso basado en roles de Azure para el plano de datos
Aplicar una directiva de clave administrada por el cliente
Deshabilitar el clasificador semántico
Deshabilitar cargas de trabajo que insertan datos en recursos externos
Crear una clave de consulta
Regeneración de una clave de administrador
Enumeración de conexiones de punto de conexión privado
Enumeración de operaciones de búsqueda
Eliminar un servicio de búsqueda

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

Requisitos previos

Una suscripción a Azure (cree una cuenta gratuita).
Visual Studio Code con un cliente REST.
La CLI de Azure se usa para obtener un token de acceso. Debe ser propietario o administrador en su suscripción de Azure.

Obtención de un token de acceso

Las llamadas API de REST de administración se autentican a través de Microsoft Entra ID. Debe proporcionar un token de acceso en la solicitud, junto con permisos para crear y configurar un recurso.

Puede usar la CLI de Azure o Azure PowerShell para crear un token de acceso.

Abrir un shell de comandos para la CLI de Azure.
Inicie sesión en la suscripción de Azure.
```
az login
```
Obtenga el identificador de inquilino y el identificador de suscripción. Si tiene varios inquilinos o suscripciones, asegúrese de usar el correcto.
```
az account show
```

Obtén 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 inicio rápido.

Inicie Visual Studio Code y seleccione el icono Extensiones.
Busque el cliente REST y seleccione Instalar.
Abra o cree un nuevo archivo denominado con una extensión de archivo .rest o .http.

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

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

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/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

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

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. Proporciona los nombres directamente o agrega nuevas variables a la colección.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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"
        }
      }

Creación de un servicio S3HD

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

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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 y Colaborador de servicio de búsqueda.

En este paso, configure su servicio de búsqueda para que reconozca un encabezado Authorization en solicitudes de datos que proporcionen un token de acceso de OAuth2.

Para usar el control de acceso basado en rol para las operaciones del plano de datos, establezca authOptions en aadOrApiKey y 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.

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

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

Aplicar una directiva de clave administrada por el cliente

Si usa el cifrado administrado por el cliente, puede habilitar "encryptionWithCMK" con "enforcement" establecido en "Enabled" (Habilitado) para que el servicio de búsqueda notifique su estado de cumplimiento.

Al habilitar esta directiva, se producirá un error en las llamadas REST que creen objetos que contengan datos confidenciales, como la 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."

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

Deshabilitar el clasificador semántico

Aunque el clasificador semántico no está activado por defecto, se podría bloquear la función a nivel de servicio para tener una mayor certeza de que no se puede utilizar.

### disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

Deshabilitar de las cargas de trabajo que insertan datos en recursos externos

Azure AI Search 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
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-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
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Enumeración de claves de API de administración

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Regeneración de las claves de API de administración

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

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Creación de claves de API de consulta

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-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
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-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/{{subscriptionId}}/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 la creación de un índice o la consulta de un índice mediante Azure Portal, las API de REST o un SDK de Azure.

Compartir a través de