Administración del servicio de Azure AI Search con la CLI de Azure

  • Artículo

Puede ejecutar scripts y comandos de la CLI de Azure en Windows, macOS, Linux o en Azure Cloud Shell para crear y configurar Azure AI Search.

Use el módulo de búsqueda az para realizar las siguientes tareas:

En ocasiones, se formulan preguntas sobre las tareas que no están en la lista anterior.

No se puede cambiar el nombre de un servidor, la región o el nivel mediante programación o en el portal. Cuando se crea un servicio, se asignan recursos dedicados. Por tanto, el cambio del hardware subyacente (tipo de nodo o ubicación), requiere un nuevo servicio.

No puede usar herramientas ni API para transferir contenido, como un índice, de un servicio a otro. Dentro de un servicio, la creación de contenido mediante programación se realiza a través de la API de REST del servicio de búsqueda o un SDK como el SDK de Azure de .NET. Aunque no hay comandos dedicados para la migración de contenido, puede escribir un script que llame a la API de REST o una biblioteca cliente para crear y cargar índices en un nuevo servicio.

Las características de administración en versión preliminar no suelen estar disponibles en el módulo az search. Si desea usar una característica en versión preliminar, use la API de REST de administración y una versión preliminar de la API.

Requisitos previos

Las versiones de la CLI de Azure ha sidolistadas en GitHub.

El módulo búsqueda az amplía la CLI de Azure con paridad completa a las versiones estables de las API REST de administración de búsqueda de.

Enumeración de servicios en una suscripción

Los siguientes comandos son de az resource y devuelven información sobre los recursos existentes y servicios ya aprovisionados en su suscripción. Si no sabe cuántos servicios de búsqueda ya se han creado, estos comandos devuelven esa información, lo que le ahorra un viaje al portal.

El primer comando devuelve todos los servicios de búsqueda.

az resource list --resource-type Microsoft.Search/searchServices --output table

De la lista de servicios, devuelva información sobre un recurso específico.

az resource list --name <search-service-name>

Lista de todos los comandos az search

Puede ver información sobre los subgrupos y los comandos disponibles en az search desde la CLI. También puede revisar la documentación.

Para ver los subgrupos disponibles dentro de az search, ejecute el siguiente comando.

az search --help

La respuesta debe ser similar a la siguiente salida.

Group
    az search : Manage Azure Search services, admin keys and query keys.
        WARNING: This command group is in preview and under development. Reference and support
        levels: https://aka.ms/CLI_refstatus
Subgroups:
    admin-key                    : Manage Azure Search admin keys.
    private-endpoint-connection  : Manage Azure Search private endpoint connections.
    private-link-resource        : Manage Azure Search private link resources.
    query-key                    : Manage Azure Search query keys.
    service                      : Manage Azure Search services.
    shared-private-link-resource : Manage Azure Search shared private link resources.

For more specific examples, use: az find "az search"

Dentro de cada subgrupo hay disponibles varios comandos. Puede ejecutar la línea siguiente para ver los comandos disponibles para el subgrupo service.

az search service --help

También puede ver los argumentos disponibles para un comando determinado.

az search service create --help

Obtención de información del servicio de búsqueda

Si conoce el grupo de recursos que contiene su servicio de búsqueda, ejecute az search service show para devolver la definición del servicio, incluido el nombre, la región, el nivel y los recuentos de réplicas y particiones. Para este comando, proporcione el grupo de recursos que contiene el servicio de búsqueda.

az search service show --name <service-name> --resource-group <search-service-resource-group-name>

Creación o eliminación de un servicio

Para crear un servicio de búsqueda, use el comando az search service create.

az search service create \
    --name <service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1

Los resultados deben tener un aspecto similar a la siguiente salida:

{
  "hostingMode": "default",
  "id": "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp",
  "identity": null,
  "location": "West US",
  "name": "my-demo-searchapp",
  "networkRuleSet": {
    "bypass": "None",
    "ipRules": []
  },
  "partitionCount": 1,
  "privateEndpointConnections": [],
  "provisioningState": "succeeded",
  "publicNetworkAccess": "Enabled",
  "replicaCount": 1,
  "resourceGroup": "demo-westus",
  "sharedPrivateLinkResources": [],
  "sku": {
    "name": "standard"
  },
  "status": "running",
  "statusDetails": "",
  "tags": null,
  "type": "Microsoft.Search/searchServices"
}

az search service delete quita el servicio y sus datos.

az search service delete --name <service-name> \
                         --resource-group  <search-service-resource-group-name> \

Creación de un servicio con reglas de IP

En función de los requisitos de seguridad, sería posible que desee crear un servicio de búsqueda con un firewall de IP configurado. Para ello, pase las direcciones IP públicas (v4) o los intervalos de CIDR al argumento ip-rules, como se muestra a continuación. Las reglas se deben separar con una coma (,) o con un punto y coma (;).

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --ip-rules "55.5.63.73;52.228.215.197;101.37.221.205"

Creación de un servicio con una identidad administrada asignada por el sistema

En algunos casos, como cuando se usa una identidad administrada para conectarse a un origen de datos, debe activar la identidad administrada asignada por el sistema. Esto se hace agregando --identity-type SystemAssigned al comando.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --identity-type SystemAssigned

Creación de un servicio con un punto de conexión privado

Los puntos de conexión privados para Azure AI Search permiten a cualquier cliente de una red virtual obtener acceso de forma segura a los datos de un índice de búsqueda a través de un vínculo privado. El punto de conexión privado usa una dirección IP del espacio de direcciones de la red virtual para el servicio de búsqueda. El tráfico de red entre el cliente y el servicio de búsqueda atraviesa la red virtual y un vínculo privado de la red troncal de Microsoft, lo que elimina la exposición a la red pública de Internet. Para obtener más información, consulte la documentación sobre la creación de un punto de conexión privado para Búsqueda de Azure AI.

En el ejemplo siguiente se muestra cómo crear un servicio de búsqueda con un punto de conexión privado.

En primer lugar, implemente un servicio de búsqueda con PublicNetworkAccess establecido en Disabled.

az search service create \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --sku Standard \
    --partition-count 1 \
    --replica-count 1 \
    --public-access Disabled

A continuación, cree una red virtual y el punto de conexión privado.

# Create the virtual network
az network vnet create \
    --resource-group <vnet-resource-group-name> \
    --location "West US" \
    --name <virtual-network-name> \
    --address-prefixes 10.1.0.0/16 \
    --subnet-name <subnet-name> \
    --subnet-prefixes 10.1.0.0/24

# Update the subnet to disable private endpoint network policies
az network vnet subnet update \
    --name <subnet-name> \
    --resource-group <vnet-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --disable-private-endpoint-network-policies true

# Get the id of the search service
id=$(az search service show \
    --resource-group <search-service-resource-group-name> \
    --name <search-service-name> \
    --query [id] \
    --output tsv)

# Create the private endpoint
az network private-endpoint create \
    --name <private-endpoint-name> \
    --resource-group <private-endpoint-resource-group-name> \
    --vnet-name <virtual-network-name> \
    --subnet <subnet-name> \
    --private-connection-resource-id $id \
    --group-id searchService \
    --connection-name <private-link-connection-name>

Por último, cree una zona DNS privada.

## Create private DNS zone
az network private-dns zone create \
    --resource-group <private-dns-resource-group-name> \
    --name "privatelink.search.windows.net"

## Create DNS network link
az network private-dns link vnet create \
    --resource-group <private-dns-resource-group-name> \
    --zone-name "privatelink.search.windows.net" \
    --name "myLink" \
    --virtual-network <virtual-network-name> \
    --registration-enabled false

## Create DNS zone group
az network private-endpoint dns-zone-group create \
   --resource-group <private-endpoint-resource-group-name>\
   --endpoint-name <private-endpoint-name> \
   --name "myZoneGroup" \
   --private-dns-zone "privatelink.search.windows.net" \
   --zone-name "searchServiceZone"

Para más información sobre cómo crear puntos de conexión privados en la CLI de Azure, consulte este Inicio rápido de Private Link.

Administración de conexiones de punto de conexión privado

Además de crear una conexión de punto de conexión privado, también puede aplicar show, update y delete a la conexión.

Para recuperar una conexión de punto de conexión privado y ver su estado, use az search private-endpoint-connection show.

az search private-endpoint-connection show \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Para actualizar la conexión, use az search private-endpoint-connection update. En el ejemplo siguiente se establece una conexión de punto de conexión privado como rechazada:

az search private-endpoint-connection update \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> 
    --status Rejected \
    --description "Rejected" \
    --actions-required "Please fix XYZ"

Para eliminar la conexión del punto de conexión privado, use az search private-endpoint-connection delete.

az search private-endpoint-connection delete \
    --name <pe-connection-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Regeneración de claves de administración

Para sustituir las claves de API de administración, use az search admin-key renew. Se crean dos claves de administración con cada servicio para el acceso autenticado. Las claves son necesarias en cada solicitud. Ambas claves de administración son funcionalmente equivalentes, concediendo acceso completo de escritura a un servicio de búsqueda con la capacidad de recuperar cualquier información, o crear y eliminar cualquier objeto. Existen dos claves, de forma que puede usar una mientras reemplaza la otra.

Solo puede regenerar una en cada momento, especificada como clave primary o secondary. Para un servicio ininterrumpido, no olvide actualizar todo el código de cliente para usar una clave secundaria mientras sustituye la clave principal. Evite cambiar las claves mientras haya operaciones en tránsito.

Como puede imaginar, si regenera las claves sin actualizar el código de cliente, se producirá un error en las solicitudes que usan la clave antigua. La regeneración de todas las claves nuevas no bloquea permanentemente el servicio y todavía puede acceder al servicio a través del portal. Después de regenerar las claves principal y secundaria, puede actualizar el código de cliente para utilizar las nuevas claves y las operaciones se reanudarán en consecuencia.

El servicio genera los valores de las claves de API. No se puede proporcionar una clave personalizada para que se use por Búsqueda de Azure AI. Del mismo modo, no hay ningún nombre definido por el usuario para las claves de API de administrador. Las referencias a la clave son cadenas fijas, ya sea primary o secondary.

az search admin-key renew \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name> \
    --key-kind primary

Los resultados deben tener un aspecto similar a la siguiente salida. Se devuelven las dos claves aunque solo cambie una a la vez.

{
  "primaryKey": <alphanumeric-guid>,
  "secondaryKey": <alphanumeric-guid>  
}

Creación o eliminación de claves de consulta

Para crear claves de API de consulta con acceso de solo lectura desde aplicaciones cliente en un índice de Azure AI Search, use az search query-key create. Las claves de consulta se usan para autenticarse en un índice específico para recuperar los resultados de búsqueda. Las claves de consulta no conceden acceso de solo lectura a otros elementos del servicio, como un índice, un origen de datos o un indexador.

No se puede proporcionar una clave para que se use por Búsqueda de Azure AI. El servicio genera las claves de API.

az search query-key create \
    --name myQueryKey \
    --resource-group <search-service-resource-group-name> \
    --service-name <search-service-name>

Escalado de réplicas y particiones

Para aumentar o disminuir réplicas y particiones, use az search service update. El aumento de las réplicas o particiones se agrega a la factura, que tiene cargos fijos y variables. Si tiene una necesidad temporal de más potencia de procesamiento, puede aumentar las réplicas y las particiones para controlar la carga de trabajo. El área de supervisión de la página Introducción del portal tiene iconos en la latencia de consulta, consultas por segundo y limitación, que indican si la capacidad actual es adecuada.

La incorporación o retirada de recursos puede tardar un unos minutos. Los ajustes de capacidad se producen en segundo plano, lo que permite que las cargas de trabajo existentes continúen. La capacidad adicional se usa para las solicitudes entrantes tan pronto como esté lista, sin ninguna configuración adicional necesaria.

La retirada de la capacidad puede ser perjudicial. Para evitar la eliminación de solicitudes, es recomendable detener todos los trabajos de indexación y del indexador antes de reducir la capacidad. Si esto no es factible, podría plantearse reducir la capacidad de forma incremental, una réplica y partición a la vez, hasta que se alcancen los nuevos niveles marcados como objetivo.

Una vez que envíe el comando, no hay forma de terminarlo a mitad de camino. Debe esperar hasta que finalice el comando antes de revisar los recuentos.

az search service update \
    --name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --partition-count 6 \
    --replica-count 6

Además de actualizar los recuentos de réplicas y particiones, también puede actualizar ip-rules, public-access y identity-type.

Los puntos de conexión privados de recursos protegidos que se crean a través de las API de Azure AI Search se conocen como recursos de vínculo privado compartido. Esto se debe a que está "compartiendo" el acceso a un recurso, como una cuenta de almacenamiento que se ha integrado con el servicio Azure Private Link.

Si usa un indexador para indexar datos en Azure AI Search y el origen de datos se encuentra en una red privada, puede crear una conexión de punto de conexión privado de salida para acceder a los datos.

Puede encontrar una lista completa de los recursos de Azure para los que puede crear puntos de conexión privados de salida desde Azure AI Search aquí, junto con los valores del identificador de grupo relacionados.

Para crear el recurso compartido de Private Link, use az search shared-private-link-resource create. Tenga en cuenta que es posible que se requiera una configuración para el origen de datos antes de ejecutar este comando.

az search shared-private-link-resource create \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name> \
    --group-id blob \
    --resource-id "/subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage"  \
    --request-message "Please approve"

Para recuperar los recursos compartidos de Private Link y ver su estado, use az search shared-private-link-resource list.

az search shared-private-link-resource list \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Debe aprobar la conexión con el comando siguiente para poder usarla. El identificador de la conexión de punto de conexión privado debe recuperarse del recurso secundario. En este caso, obtenemos el identificador de la conexión de az storage.

id = (az storage account show -n myBlobStorage --query "privateEndpointConnections[0].id")

az network private-endpoint-connection approve --id $id

Para eliminar el recurso compartido de Private Link, use az search shared-private-link-resource delete.

az search shared-private-link-resource delete \
    --name <spl-name> \
    --service-name <search-service-name> \
    --resource-group <search-service-resource-group-name>

Para obtener más información sobre cómo configurar recursos de vínculo privado compartido, consulte realizar conexiones de indexador a través de un punto de conexión privado.

Pasos siguientes

Cree un índice y consulte un índice mediante el portal, API REST o el SDK de .NET.