Administración del servicio Azure Cognitive Search con API REST

En este artículo, aprenderá a crear y configurar un servicio Azure Cognitive Search mediante las API 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. Establezca una versión preliminar de la API para acceder a las características en versión preliminar.

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.

  • Postman u otro cliente REST que envía solicitudes HTTP

  • Azure Active Directory (Azure AD) a fin de obtener un token de portador para la autenticación de solicitud

Creación de una entidad de seguridad

Las llamadas API REST de administración se autentican mediante Azure Active Directory (Azure AD). Necesitará una entidad de seguridad para el cliente, junto con permisos para crear y configurar un recurso. En esta sección se explica cómo crear una entidad de seguridad y asignar un rol.

Los pasos siguientes proceden de "Procedimiento para llamar a las API REST con Postman".

Una manera fácil de generar el identificador de cliente y la contraseña necesarios consiste en usar la característica Pruébelo en el artículo Creación de una entidad de servicio.

  1. En Creación de una entidad de servicio, seleccione Pruébelo. Inicie sesión en la suscripción de Azure.

  2. Primero, obtenga el id. de la suscripción. En la consola, escriba el siguiente comando:

    az account show --query id -o tsv
    
  3. Cree un grupo de recursos para la entidad de seguridad:

    az group create -l 'westus2' -n 'MyResourceGroup'
    
  4. Pegue el comando siguiente. Reemplace los valores de marcador de posición por valores válidos: nombre descriptivo de entidad de seguridad, identificador de suscripción, nombre del grupo de recursos. Presione Entrar para ejecutar el comando. Tenga en cuenta que la entidad de seguridad tiene permisos de "propietario", necesarios para crear o actualizar un recurso de Azure.

    az ad sp create-for-rbac --name mySecurityPrincipalName \
                             --role owner \
                             --scopes /subscriptions/mySubscriptionID/resourceGroups/myResourceGroupName
    

    Usará "appId", "password" y "tenantId" para las variables "clientId", "clientSecret" y "tenantId" en la sección siguiente.

Configuración de Postman

Los pasos siguientes proceden de esta entrada de blog si necesita más detalles.

  1. Inicie una nueva colección de Postman y edite sus propiedades. En la pestaña Variables, cree las variables siguientes:

    Variable Descripción
    clientId Proporcione el "appID" generado anteriormente que ha creado en Azure AD.
    clientSecret Proporcione la "contraseña" que se ha creado para el cliente.
    tenantId Proporcione el "inquilino" que se ha devuelto en el paso anterior.
    subscriptionId Proporcione el identificador de suscripción para la suscripción.
    resource Escriba https://management.azure.com/. Este recurso de Azure se usa para todas las operaciones del plano de control.
    bearerToken (déjelo en blanco; el token se genera mediante programación)
  2. En la pestaña Autorización, seleccione Token de portador como tipo.

  3. En el campo Token, especifique el marcador de posición de la variable {{{{bearerToken}}}}.

  4. En la pestaña Script previo a la solicitud, pegue el siguiente script:

    pm.test("Check for collectionVariables", function () {
        let vars = ['clientId', 'clientSecret', 'tenantId', 'subscriptionId'];
        vars.forEach(function (item, index, array) {
            console.log(item, index);
            pm.expect(pm.collectionVariables.get(item), item + " variable not set").to.not.be.undefined;
            pm.expect(pm.collectionVariables.get(item), item + " variable not set").to.not.be.empty; 
        });
    
        if (!pm.collectionVariables.get("bearerToken") || Date.now() > new Date(pm.collectionVariables.get("bearerTokenExpiresOn") * 1000)) {
            pm.sendRequest({
                url: 'https://login.microsoftonline.com/' + pm.collectionVariables.get("tenantId") + '/oauth2/token',
                method: 'POST',
                header: 'Content-Type: application/x-www-form-urlencoded',
                body: {
                    mode: 'urlencoded',
                    urlencoded: [
                        { key: "grant_type", value: "client_credentials", disabled: false },
                        { key: "client_id", value: pm.collectionVariables.get("clientId"), disabled: false },
                        { key: "client_secret", value: pm.collectionVariables.get("clientSecret"), disabled: false },
                        { key: "resource", value: pm.collectionVariables.get("resource") || "https://management.azure.com/", disabled: false }
                    ]
                }
            }, function (err, res) {
                if (err) {
                    console.log(err);
                } else {
                    let resJson = res.json();
                    pm.collectionVariables.set("bearerTokenExpiresOn", resJson.expires_on);
                    pm.collectionVariables.set("bearerToken", resJson.access_token);
                }
            });
        }
    });
    
  5. Guarde la colección.

Ahora que Postman está configurado, puede enviar llamadas REST similares a las descritas en este artículo. Actualizará el punto de conexión y solicitará el cuerpo cuando corresponda.

Enumeración de servicios de búsqueda

Devuelve todos los servicios de búsqueda de la suscripción actual, incluida la información detallada del servicio:

GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2021-04-01-preview

Creación o actualización de un servicio

Crea o actualiza un servicio de búsqueda en la suscripción actual:

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
{
  "location": "{{region}}",
  "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.

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
{
  "location": "{{region}}",
  "sku": {
    "name": "Standard3"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "hostingMode": "HighDensity"
  }
}

(versión preliminar) Habilitación de la autenticación basada en roles de Azure para el plano de datos

Para usar el control de acceso basado en roles de Azure (RBAC de Azure), establezca "authOptions" en "aadOrApiKey" y envíe la solicitud.

Si quiere usar RBAC de Azure exclusivamente, desactive la autenticación de clave de API siguiendo una segunda solicitud, y esta vez establezca "disableLocalAuth" en "false".

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
{
  "location": "{{region}}",
  "tags": {
    "app-name": "My e-commerce app"
  },
  "sku": {
    "name": "standard"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "hostingMode": "default",
    "disableLocalAuth": false,
    "authOptions": "aadOrApiKey"
    }
  }
}

(versión preliminar) Aplicación de 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 que crean objetos con 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."

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
{
  "location": "westus",
  "sku": {
    "name": "standard"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "hostingMode": "default",
    "encryptionWithCmk": {
      "enforcement": "Enabled",
      "encryptionComplianceStatus": "Compliant"
    },
  }
}

Aunque la búsqueda semántica no está habilitada de forma predeterminada, puede bloquear la característica en el nivel de servicio.

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
    {
      "location": "{{region}}",
      "sku": {
        "name": "standard"
      },
      "properties": {
        "semanticSearch": "disabled"
      }
    }

(versión preliminar) Deshabilitación de cargas de trabajo que insertan datos en recursos externos

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

PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-preview
{
  "location": "{{region}}",
  "sku": {
    "name": "standard"
  },
  "properties": {
    "replicaCount": 1,
    "partitionCount": 1,
    "hostingMode": "default",
    "disabledDataExfiltrationOptions": [
      "All"
    ]
  }
}

Pasos siguientes

Una vez que se configura un servicio de búsqueda, los pasos siguientes incluyen crear un índice o consultar un índice mediante el portal, las API REST o el SDK de .NET.