Administración de un servicio Azure AI Search con PowerShell
Para crear y configurar Azure AI Search se pueden ejecutar scripts y cmdlets de PowerShell en Windows, Linux, o en Azure Cloud Shell.
Use el módulo de Az.Search para realizar las siguientes tareas:
- Enumerar servicios de búsqueda en una suscripción
- Devolver información del servicio
- Crear o eliminar un servicio
- Creación de un servicio con un punto de conexión privado
- Regenerar claves de API de administración
- Crear o eliminar claves de API de consulta
- Escalar o reducir verticalmente con réplicas y particiones
- Creación de un recurso compartido de vínculo privado
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.
El módulo de Az.Search amplía Azure PowerShell con paridad completa a las versiones estables de las API de REST de administración de búsqueda de.
Comprobación de versiones y carga de módulos
Los ejemplos de este artículo son interactivos y requieren permisos elevados. Se requiere PowerShell local y Azure PowerShell (módulo Az).
Comprobación de versión de PowerShell
Instale la versión más reciente de PowerShell si no la tiene.
$PSVersionTable.PSVersion
Carga de Azure PowerShell
Si no sabe si Az está instalado, ejecute el siguiente comando como un paso de verificación.
Get-InstalledModule -Name Az
Algunos sistemas no cargan automáticamente los módulos. Si se produce un error en el comando anterior, intente cargar el módulo, y si se vuelve a producir un error, regrese a las instrucciones de instalación de Azure PowerShell para ver si falta algún paso.
Import-Module -Name Az
Conexión a Azure con un token de inicio de sesión de explorador
Puede usar sus credenciales de inicio de sesión del portal para conectarse a una suscripción en PowerShell. También puede autenticarse de forma no interactiva con una entidad de servicio.
Connect-AzAccount
Si mantiene varias suscripciones de Azure, establezca la suscripción de Azure. Para ver una lista de las suscripciones actuales, ejecute este comando.
Get-AzSubscription | sort SubscriptionName | Select SubscriptionName
Para especificar la suscripción, ejecute el siguiente comando. En el ejemplo siguiente, el nombre de la suscripción es ContosoSubscription.
Select-AzSubscription -SubscriptionName ContosoSubscription
Enumeración de servicios en una suscripción
Los siguientes comandos son de Az.Resources, que 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.
Get-AzResource -ResourceType Microsoft.Search/searchServices | ft
De la lista de servicios, devuelva información sobre un recurso específico.
Get-AzResource -ResourceName <service-name>
Los resultados deben tener un aspecto similar a la siguiente salida.
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : westus
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Importar Az.Search
Los comandos de Az.Search no están disponibles hasta que cargue el módulo.
Install-Module -Name Az.Search -Scope CurrentUser
Enumerar todos los comandos Az.Search
Como paso de verificación, devuelva una lista de comandos proporcionados en el módulo.
Get-Command -Module Az.Search
Los resultados deben tener un aspecto similar a la siguiente salida.
CommandType Name Version Source
----------- ---- ------- ------
Cmdlet Get-AzSearchAdminKeyPair 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Get-AzSearchPrivateLinkResource 0.10.0 Az.Search
Cmdlet Get-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Get-AzSearchService 0.10.0 Az.Search
Cmdlet Get-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet New-AzSearchAdminKey 0.10.0 Az.Search
Cmdlet New-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet New-AzSearchService 0.10.0 Az.Search
Cmdlet New-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Remove-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Remove-AzSearchQueryKey 0.10.0 Az.Search
Cmdlet Remove-AzSearchService 0.10.0 Az.Search
Cmdlet Remove-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Cmdlet Set-AzSearchPrivateEndpointConnection 0.10.0 Az.Search
Cmdlet Set-AzSearchService 0.10.0 Az.Search
Cmdlet Set-AzSearchSharedPrivateLinkResource 0.10.0 Az.Search
Si tiene una versión anterior del paquete, actualice el módulo para obtener la funcionalidad más reciente.
Update-Module -Name Az.Search
Obtención de información del servicio de búsqueda
Después de que Az.Search se importe y sepa el grupo de recursos que contiene el servicio de búsqueda, ejecute Get-AzSearchService 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.
Get-AzSearchService -ResourceGroupName <resource-group-name>
Los resultados deben tener un aspecto similar a la siguiente salida.
Name : my-demo-searchapp
ResourceGroupName : demo-westus
ResourceType : Microsoft.Search/searchServices
Location : West US
Sku : Standard
ReplicaCount : 1
PartitionCount : 1
HostingMode : Default
ResourceId : /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Creación o eliminación de un servicio
New-AzSearchService se usa para crear un nuevo servicio de búsqueda.
New-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name> -Sku "Standard" -Location "West US" -PartitionCount 3 -ReplicaCount 3 -HostingMode Default
Los resultados deben tener un aspecto similar a la siguiente salida.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Id : /subscriptions/<alphanumeric-subscription-ID>/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 3
PartitionCount : 3
HostingMode : Default
Tags
Remove-AzSearchService se usa para eliminar un servicio y sus datos.
Remove-AzSearchService -ResourceGroupName <resource-group-name> -Name <search-service-name>
Se le pide que confirme la acción.
Confirm
Are you sure you want to remove Search Service 'pstestazuresearch01'?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
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, defina primero las reglas de IP y, a continuación, páselas al parámetro IPRuleList, como se muestra a continuación.
$ipRules = @([pscustomobject]@{Value="55.5.63.73"},
[pscustomobject]@{Value="52.228.215.197"},
[pscustomobject]@{Value="101.37.221.205"})
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IPRuleList $ipRules
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 -IdentityType SystemAssigned al comando.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 3 -ReplicaCount 3 `
-HostingMode Default `
-IdentityType SystemAssigned
Creación de un servicio S3HD
Para crear un servicio S3HD, se usa una combinación de -Sku y -HostingMode. Establezca -Sku en Standard3 y -HostingMode en HighDensity.
New-AzSearchService -ResourceGroupName <resource-group-name> `
-Name <search-service-name> `
-Sku Standard3 `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 3 `
-HostingMode HighDensity
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 más información, consulte Creación de puntos de conexión privados para Azure AI Search.
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.
$searchService = New-AzSearchService `
-ResourceGroupName <search-service-resource-group-name> `
-Name <search-service-name> `
-Sku Standard `
-Location "West US" `
-PartitionCount 1 -ReplicaCount 1 `
-HostingMode Default `
-PublicNetworkAccess Disabled
A continuación, cree una red virtual, una conexión de red privada y el punto de conexión privado.
# Create the subnet
$subnetConfig = New-AzVirtualNetworkSubnetConfig `
-Name <subnet-name> `
-AddressPrefix 10.1.0.0/24 `
-PrivateEndpointNetworkPolicies Disabled
# Create the virtual network
$virtualNetwork = New-AzVirtualNetwork `
-ResourceGroupName <vm-resource-group-name> `
-Location "West US" `
-Name <virtual-network-name> `
-AddressPrefix 10.1.0.0/16 `
-Subnet $subnetConfig
# Create the private network connection
$privateLinkConnection = New-AzPrivateLinkServiceConnection `
-Name <private-link-name> `
-PrivateLinkServiceId $searchService.Id `
-GroupId searchService
# Create the private endpoint
$privateEndpoint = New-AzPrivateEndpoint `
-Name <private-endpoint-name> `
-ResourceGroupName <private-endpoint-resource-group-name> `
-Location "West US" `
-Subnet $virtualNetwork.subnets[0] `
-PrivateLinkServiceConnection $privateLinkConnection
Por último, cree una zona DNS privada.
## Create private dns zone
$zone = New-AzPrivateDnsZone `
-ResourceGroupName <private-dns-resource-group-name> `
-Name "privatelink.search.windows.net"
## Create dns network link
$link = New-AzPrivateDnsVirtualNetworkLink `
-ResourceGroupName <private-dns-link-resource-group-name> `
-ZoneName "privatelink.search.windows.net" `
-Name "myLink" `
-VirtualNetworkId $virtualNetwork.Id
## Create DNS configuration
$config = New-AzPrivateDnsZoneConfig `
-Name "privatelink.search.windows.net" `
-PrivateDnsZoneId $zone.ResourceId
## Create DNS zone group
New-AzPrivateDnsZoneGroup `
-ResourceGroupName <private-dns-zone-resource-group-name> `
-PrivateEndpointName <private-endpoint-name> `
-Name 'myZoneGroup' `
-PrivateDnsZoneConfig $config
Para más información sobre cómo crear puntos de conexión privados en PowerShell, 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 Get, Set y Remove a la conexión.
Get-AzSearchPrivateEndpointConnection se usa para recuperar una conexión de punto de conexión privado y para ver su estado.
Get-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>
Set-AzSearchPrivateEndpointConnection se usa para actualizar la conexión. En el ejemplo siguiente se establece una conexión de punto de conexión privado como rechazada:
Set-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name> -Status Rejected -Description "Rejected"
Remove-AzSearchPrivateEndpointConnection se usa para eliminar la conexión de punto de conexión privado.
Remove-AzSearchPrivateEndpointConnection -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <pe-connection-name>
Regeneración de claves de administración
New-AzSearchAdminKey se usa para sustituir las claves de API de administración. 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.
New-AzSearchAdminKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -KeyKind Primary
Los resultados deben tener un aspecto similar a la siguiente salida. Se devuelven las dos claves aunque solo cambie una a la vez.
Primary Secondary
------- ---------
<alphanumeric-guid> <alphanumeric-guid>
Creación o eliminación de claves de consulta
New-AzSearchQueryKey se usa para crear claves de API de consulta para el acceso de solo lectura desde las aplicaciones cliente hasta un índice de Azure AI Search. 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.
New-AzSearchQueryKey -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <query-key-name>
Escalado de réplicas y particiones
Set-AzSearchService se utiliza para aumentar o reducir las réplicas y particiones para reajustar los recursos facturables dentro del servicio. 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.
Set-AzSearchService -ResourceGroupName <search-service-resource-group-name> -Name <search-service-name> -PartitionCount 6 -ReplicaCount 6
Los resultados deben tener un aspecto similar a la siguiente salida.
ResourceGroupName : demo-westus
Name : my-demo-searchapp
Location : West US
Sku : Standard
ReplicaCount : 6
PartitionCount : 6
HostingMode : Default
Id : /subscriptions/65a1016d-0f67-45d2-b838-b8f373d6d52e/resourceGroups/demo-westus/providers/Microsoft.Search/searchServices/my-demo-searchapp
Creación de un recurso compartido de vínculo privado
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.
New-AzSearchSharedPrivateLinkResource se usa para crear el recurso compartido de vínculo privado. Tenga en cuenta que es posible que se requiera una configuración para el origen de datos antes de ejecutar este comando.
New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-serviceresource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId <group-id> -RequestMessage "Please approve"
Get-AzSearchSharedPrivateLinkResource le permite recuperar los recursos compartidos de vínculo privado y ver su estado.
Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name>
Debe aprobar la conexión con el comando siguiente para poder usarla.
Approve-AzPrivateEndpointConnection `
-Name <spl-name> `
-ServiceName <search-service-name> `
-ResourceGroupName <search-service-resource-group-name> `
-Description = "Approved"
Remove-AzSearchSharedPrivateLinkResource se usa para eliminar el recurso compartido de vínculo privado.
$job = Remove-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -Force -AsJob
$job | Get-Job
Para obtener información detallada sobre la configuración de recursos compartidos de vínculo privado, consulte la documentación sobre la creación de 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.