Administrar el servicio de Azure AI Search con las API de REST
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.
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.
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.
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": [ . . . ] }
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"
}
}
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"
}
}
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"
}
}
}
}
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"
}
}
}
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"
}
}
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"
}
}
### 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}}
### 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}}
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}}
### 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}}
### 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}}
### 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}}
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.