Leer en inglés

Compartir a través de


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.

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

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.

  1. Abrir un shell de comandos para la CLI de Azure.

  2. Inicie sesión en la suscripción de Azure.

    az login
    
  3. 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
    
  4. 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.

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

  2. Busque el cliente REST y seleccione Instalar.

    Captura de pantalla del comando install.

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

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