Criar e gerenciar trabalhos elásticos usando o PowerShell (visualização)

  • Artigo

Aplica-se a:Banco de Dados SQL do Azure

Este artigo fornece um tutorial e exemplos para começar a trabalhar com trabalhos elásticos usando o PowerShell. As tarefas elásticas permitem a execução de um ou mais scripts Transact-SQL (T-SQL) em paralelo em muitas bases de dados.

Neste tutorial completo, você aprenderá as etapas necessárias para executar uma consulta em vários bancos de dados:

  • Criar um agente de trabalho elástico
  • Criar credenciais de tarefa para que as tarefas possam executar scripts nos respetivos destinos
  • Defina os destinos (servidores, pools elásticos, bancos de dados) contra os quais deseja executar o trabalho
  • Criar credenciais de escopo de banco de dados nos bancos de dados de destino para que o agente se conecte e execute trabalhos
  • Criar um trabalho
  • Adicionar passos de tarefa a uma tarefa
  • Iniciar a execução de uma tarefa
  • Monitorizar uma tarefa

Nota

Os trabalhos elásticos estão em pré-visualização. As funcionalidades atualmente em pré-visualização estão disponíveis em termos de utilização suplementares, rever os termos legais que se aplicam às funcionalidades do Azure que estão em pré-visualização. A Base de Dados SQL do Azure fornece pré-visualizações para lhe dar a oportunidade de avaliar e partilhar comentários com o grupo de produtos sobre funcionalidades antes de estas se tornarem disponíveis ao público (GA).

Pré-requisitos

Os trabalhos de banco de dados elástico têm um conjunto de cmdlets do PowerShell.

Esses cmdlets foram atualizados em novembro de 2023.

Instalar os cmdlets de trabalhos elásticos mais recentes

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Se ainda não estiver presente, instale as Az.Sql versões mais recentes dos módulos e SqlServer . Execute os seguintes comandos no PowerShell com acesso administrativo.

# installs the latest PackageManagement and PowerShellGet packages
Find-Package PackageManagement | Install-Package -Force
Find-Package PowerShellGet | Install-Package -Force

# Restart your powershell session with administrative access

# Install and import the Az.Sql module, then confirm
Install-Module -Name Az.Sql
Import-Module Az.Sql
Install-Module -Name SqlServer
Import-Module SqlServer

Para obter detalhes, consulte Instalar o módulo SQL Server PowerShell.

Criar os recursos necessários

A criação de um agente de trabalho elástico requer um banco de dados (S1 ou superior) para uso como o banco de dados de trabalho elástico.

O script a seguir cria um novo grupo de recursos, servidor e banco de dados para uso como o banco de dados de trabalho elástico. O segundo script cria um segundo servidor com dois bancos de dados em branco para executar trabalhos.

Os trabalhos elásticos não têm requisitos de nomenclatura específicos para que você possa usar as convenções de nomenclatura desejadas, desde que estejam em conformidade com quaisquer requisitos do Azure. Se você já tiver criado um banco de dados em branco para o servidor como o banco de dados de trabalho elástico, pule para Criar o agente de trabalho elástico.

Configurar uma regra de firewall com New-AzSqlServerFirewallRule é desnecessário ao usar o endpoint privado de trabalhos elásticos.

# Sign in to your Azure account
Connect-AzAccount

# The SubscriptionId in which to create these objects
$SubscriptionId = '<your subscription id>'
# Set subscription context, important if you have access to more than one subscription.
Set-AzContext -SubscriptionId $subscriptionId 

# Create a resource group
Write-Output "Creating a resource group..."
$resourceGroupName = Read-Host "Please enter a resource group name"
$location = Read-Host "Please enter an Azure Region, for example westus2"
$rg = New-AzResourceGroup -Name $resourceGroupName -Location $location
$rg

# Create an Azure SQL logical server
Write-Output "Creating a server..."
$agentServerName = Read-Host "Please enter an agent server name"
$agentServerName = $agentServerName + "-" + [guid]::NewGuid()
$adminLogin = Read-Host "Please enter the server admin name"
$adminPassword = Read-Host "Please enter the server admin password"
$adminPasswordSecure = ConvertTo-SecureString -String $AdminPassword -AsPlainText -Force
$adminCred = New-Object -TypeName "System.Management.Automation.PSCredential" -ArgumentList $adminLogin, $adminPasswordSecure
$parameters = @{
    ResourceGroupName = $resourceGroupName 
    Location = $location
    ServerName = $agentServerName 
    SqlAdministratorCredentials = ($adminCred)    
}
$agentServer = New-AzSqlServer @parameters

# Set server firewall rules to allow all Azure IPs
# Unnecessary if using an elastic jobs private endpoint
Write-Output "Creating a server firewall rule..."
$agentServer | New-AzSqlServerFirewallRule -AllowAllAzureIPs -FirewallRuleName "Allowed IPs"
$agentServer

# Create the job database
Write-Output "Creating a blank database to be used as the Job Database..."
$jobDatabaseName = "JobDatabase"
$parameters = @{
    ResourceGroupName = $resourceGroupName 
    ServerName = $agentServerName 
    DatabaseName = $jobDatabaseName 
    RequestedServiceObjectiveName = "S1"
}
$jobDatabase = New-AzSqlDatabase @parameters
$jobDatabase

# Create a target server and sample databases - uses the same credentials
Write-Output "Creating target server..."
$targetServerName = Read-Host "Please enter a target server name"
$targetServerName = $targetServerName + "-" + [guid]::NewGuid()
$parameters = @{
    ResourceGroupName= $resourceGroupName
    Location= $location 
    ServerName= $targetServerName
    ServerVersion= "12.0"
    SqlAdministratorCredentials= ($adminCred)
}
$targetServer = New-AzSqlServer @parameters

# Set target server firewall rules to allow all Azure IPs
# Unnecessary if using an elastic jobs private endpoint
$targetServer | New-AzSqlServerFirewallRule -AllowAllAzureIPs 

# Set the target firewall to include your desired IP range. 
# Change the following -StartIpAddress and -EndIpAddress values.
$parameters = @{
    StartIpAddress = "0.0.0.0" 
    EndIpAddress = "0.0.0.0"
    FirewallRuleName = "AllowAll"
}
$targetServer | New-AzSqlServerFirewallRule @parameters
$targetServer

# Create two sample databases to execute jobs against
$parameters = @{
    ResourceGroupName = $resourceGroupName 
    ServerName = $targetServerName 
    DatabaseName = "database1"
}
$db1 = New-AzSqlDatabase @parameters
$db1
$parameters = @{
    ResourceGroupName = $resourceGroupName 
    ServerName = $targetServerName 
    DatabaseName = "database2"
}
$db2 = New-AzSqlDatabase @parameters
$db2

Criar o agente de trabalho elástico

Um agente de trabalho elástico é um recurso do Azure para criar, executar e gerenciar trabalhos. O agente executa tarefas com base num agendamento ou como uma tarefa única. Todas as datas e horas em trabalhos elásticos estão no fuso horário UTC.

O cmdlet New-AzSqlElasticJobAgent requer que um banco de dados no Banco de Dados SQL do Azure já exista, portanto, os resourceGroupNameparâmetros , serverNamee databaseName devem apontar para recursos existentes. Da mesma forma, Set-AzSqlElasticJobAgent pode ser usado para modificar o agente de trabalho elástico.

Para criar um novo agente de trabalho elástico usando a autenticação do Microsoft Entra com uma identidade gerenciada atribuída pelo usuário, use os IdentityType argumentos e IdentityID de New-AzSqlElasticJobAgent:

Write-Output "Creating job agent..."
$agentName = Read-Host "Please enter a name for your new elastic job agent"
$parameters = @{
    Name = $agentName 
    IdentityType = "UserAssigned" 
    IdentityID = "/subscriptions/abcd1234-caaf-4ba9-875d-f1234/resourceGroups/contoso-jobDemoRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-UMI"
}
$jobAgent = $jobDatabase | New-AzSqlElasticJobAgent @parameters
$jobAgent

Para criar um novo agente de trabalho elástico usando credenciais IdentityType de escopo de banco de dados e IdentityID não são fornecidas.

Criar a autenticação de trabalho

O agente de trabalho elástico deve ser capaz de autenticar em cada servidor ou banco de dados de destino.

Conforme abordado em Criar autenticação de agente de trabalho:

  • Use usuários de banco de dados mapeados para UMI (identidade gerenciada atribuída pelo usuário) para autenticar no(s) servidor(es)/banco(s) de dados de destino.
    • Usar um UMI com autenticação do Microsoft Entra (anteriormente Azure Ative Directory) é o método recomendado. Os cmdlets do PowerShell agora têm novos argumentos para dar suporte à autenticação do Microsoft Entra com um UMI.
    • Este é o método de autenticação recomendado.
  • Use usuários de banco de dados mapeados para credenciais de escopo de banco de dados em cada banco de dados.
    • Anteriormente, as credenciais de escopo de banco de dados eram a única opção para o agente de trabalho elástico se autenticar nos destinos.

Usar a autenticação do Microsoft Entra com um UMI para autenticação de destinos

Para usar o método recomendado de autenticação do Microsoft Entra (anteriormente Azure Ative Directory) para uma identidade gerenciada atribuída pelo usuário (UMI), siga estas etapas. O agente de trabalho elástico se conecta ao(s) servidor(es) lógico(s)/bancos de dados de destino desejado(s) por meio da autenticação do Entra.

Além dos usuários de login e banco de dados, observe a GRANT adição dos comandos no script a seguir. Estas permissões são necessárias para o script que escolhemos para esta tarefa de exemplo. Seus trabalhos podem exigir permissões diferentes. Como o exemplo cria uma nova tabela nos bancos de dados de destino, o usuário do banco de dados em cada banco de dados de destino precisa das permissões adequadas para ser executado com êxito.

Em cada servidor(es)/banco de dados de destino, crie um usuário contido mapeado para a UMI.

  • Se o trabalho elástico tiver destinos de servidor lógico ou pool, você deverá criar o usuário contido mapeado para o UMI no master banco de dados do servidor lógico de destino.
  • Por exemplo, para criar um logon de banco de dados contido no banco de dados e um usuário no master banco de dados de usuários, com base na identidade gerenciada atribuída pelo usuário (UMI) chamada job-agent-UMI:
$targetServer = '<target server name>'
$adminLogin = '<username>'
$adminPassword = '<password>'

# For the target logical server, in the master database
# Create the login named [job-agent-UMI] based on the UMI [job-agent-UMI], and a user
$params = @{
  'database' = 'master'
  'serverInstance' =  $targetServer.ServerName + '.database.windows.net'
  'username' = $adminLogin
  'password' = $adminPassword
  'outputSqlErrors' = $true
  'query' = 'CREATE LOGIN [job-agent-UMI] FROM EXTERNAL PROVIDER;'
}
Invoke-SqlCmd @params
$params.query = "CREATE USER [job-agent-UMI] FROM LOGIN [job-agent-UMI]"
Invoke-SqlCmd @params

# For each target database in the target logical server
# Create a database user from the job-agent-UMI login 
$targetDatabases = @( $db1.DatabaseName, $Db2.DatabaseName )
$createJobUserScript =  "CREATE USER [job-agent-UMI] FROM LOGIN [job-agent-UMI]"

# Grant permissions as necessary. For example ALTER and CREATE TABLE:
$grantAlterSchemaScript = "GRANT ALTER ON SCHEMA::dbo TO [job-agent-UMI]" 
$grantCreateScript = "GRANT CREATE TABLE TO [job-agent-UMI]"

$targetDatabases | % {
  $params.database = $_
  $params.query = $createJobUserScript
  Invoke-SqlCmd @params
  $params.query = $grantAlterSchemaScript
  Invoke-SqlCmd @params
  $params.query = $grantCreateScript
  Invoke-SqlCmd @params
}

Usar credenciais de escopo de banco de dados para autenticação em destinos

Os agentes de trabalho usam credenciais especificadas pelo grupo-alvo durante a execução e executam scripts. Essas credenciais de escopo de banco de dados também são usadas para se conectar ao master banco de dados para descobrir todos os bancos de dados em um servidor ou pool elástico, quando qualquer um deles é usado como o tipo de membro do grupo de destino.

As credenciais com escopo de banco de dados devem ser criadas no banco de dados de tarefas. Todas as bases de dados de destino precisam de um início de sessão com permissões suficientes para a tarefa ser concluída com êxito.

Além das credenciais na imagem, observe a adição dos GRANT comandos no script a seguir. Estas permissões são necessárias para o script que escolhemos para esta tarefa de exemplo. Seus trabalhos podem exigir permissões diferentes. Como o exemplo cria uma nova tabela nos bancos de dados de destino, o usuário do banco de dados em cada banco de dados de destino precisa das permissões adequadas para ser executado com êxito.

O login/usuário em cada servidor/banco de dados de destino deve ter o mesmo nome que a identidade da credencial com escopo de banco de dados para o usuário de trabalho e a mesma senha que a credencial de escopo de banco de dados para o usuário de trabalho. Onde o script do PowerShell usa <strong jobuser password here>, use a mesma senha por toda parte.

O exemplo a seguir usa credenciais com escopo de banco de dados. Para criar as credenciais de trabalho necessárias (no banco de dados de tarefas), execute o seguinte script, que usa a Autenticação SQL para se conectar ao(s) servidor(es)/banco de dados de destino:

# For the target logical server, in the master database
# Create the master user login, master user, and job user login
$targetServer = '<target server name>'
$adminLogin = '<username>'
$adminPassword = '<password>'

$params = @{
  'database' = 'master'
  'serverInstance' =  $targetServer.ServerName + '.database.windows.net'
  'username' = $adminLogin
  'password' = $adminPassword
  'outputSqlErrors' = $true
  'query' = 'CREATE LOGIN adminuser WITH PASSWORD=''<strong adminuser password here>'''
}
Invoke-SqlCmd @params
$params.query = "CREATE USER adminuser FROM LOGIN adminuser"
Invoke-SqlCmd @params
$params.query = 'CREATE LOGIN jobuser WITH PASSWORD=''<strong jobuser password here>'''
Invoke-SqlCmd @params

# For each target database in the target logical server
# Create the jobuser from jobuser login and check permission for script execution
$targetDatabases = @( $db1.DatabaseName, $Db2.DatabaseName )
$createJobUserScript =  "CREATE USER jobuser FROM LOGIN jobuser"

# Grant permissions as necessary. For example ALTER and CREATE TABLE:
$grantAlterSchemaScript = "GRANT ALTER ON SCHEMA::dbo TO jobuser"
$grantCreateScript = "GRANT CREATE TABLE TO jobuser"

$targetDatabases | % {
  $params.database = $_
  $params.query = $createJobUserScript
  Invoke-SqlCmd @params
  $params.query = $grantAlterSchemaScript
  Invoke-SqlCmd @params
  $params.query = $grantCreateScript
  Invoke-SqlCmd @params
}

# Create job credential in job database for admin user
Write-Output "Creating job credentials..."
$loginPasswordSecure = (ConvertTo-SecureString -String '<strong jobuser password here>' -AsPlainText -Force)
$loginadminuserPasswordSecure = (ConvertTo-SecureString -String '<strong adminuser password here>' -AsPlainText -Force)

$adminCred = New-Object -TypeName "System.Management.Automation.PSCredential" -ArgumentList "adminuser", $loginadminuserPasswordSecure
$adminCred = $jobAgent | New-AzSqlElasticJobCredential -Name "adminuser" -Credential $adminCred

$jobCred = New-Object -TypeName "System.Management.Automation.PSCredential" -ArgumentList "jobuser", $loginPasswordSecure
$jobCred = $jobAgent | New-AzSqlElasticJobCredential -Name "jobuser" -Credential $jobCred

Definir servidores e bancos de dados de destino

Um grupo de destino define o conjunto de um ou mais bases de dados onde será executado um passo de tarefa.

O trecho a seguir cria dois grupos-alvo: serverGroup, e serverGroupExcludingDb2. serverGroup destina-se a todos os bancos de dados existentes no servidor no momento da execução e serverGroupExcludingDb2 destina-se a todos os bancos de dados no servidor, exceto TargetDb2:

Write-Output "Creating test target groups..."
# create ServerGroup target group
$serverGroup = $jobAgent | New-AzSqlElasticJobTargetGroup -Name 'ServerGroup'
$serverGroup | Add-AzSqlElasticJobTarget -ServerName $targetServerName -RefreshCredentialName $adminCred.CredentialName

# create ServerGroup with an exclusion of db2
$serverGroupExcludingDb2 = $jobAgent | New-AzSqlElasticJobTargetGroup -Name 'ServerGroupExcludingDb2'
$serverGroupExcludingDb2 | Add-AzSqlElasticJobTarget -ServerName $targetServerName -RefreshCredentialName $adminCred.CredentialName
$serverGroupExcludingDb2 | Add-AzSqlElasticJobTarget -ServerName $targetServerName -Database $db2.DatabaseName -Exclude

Criar um trabalho e etapas

Este exemplo define um trabalho e duas etapas de trabalho para que o trabalho seja executado. A primeira etapa do trabalho () cria uma nova tabela (step1Step1Table) em cada banco de dados do grupo-alvoServerGroup. A segunda etapa de trabalho () cria uma nova tabela (step2Step2Table) em cada banco de dados, exceto para , porque o grupo-alvo definido anteriormente especificado para TargetDb2excluí-lo.

Write-Output "Creating a new job..."
$jobName = "Job1"
$job = $jobAgent | New-AzSqlElasticJob -Name $jobName -RunOnce
$job

Write-Output "Creating job steps..."
$sqlText1 = "IF NOT EXISTS (SELECT * FROM sys.tables WHERE object_id = object_id('Step1Table')) CREATE TABLE [dbo].[Step1Table]([TestId] [int] NOT NULL);"
$sqlText2 = "IF NOT EXISTS (SELECT * FROM sys.tables WHERE object_id = object_id('Step2Table')) CREATE TABLE [dbo].[Step2Table]([TestId] [int] NOT NULL);"

$job | Add-AzSqlElasticJobStep -Name "step1" -TargetGroupName $serverGroup.TargetGroupName -CredentialName $jobCred.CredentialName -CommandText $sqlText1
$job | Add-AzSqlElasticJobStep -Name "step2" -TargetGroupName $serverGroupExcludingDb2.TargetGroupName -CredentialName $jobCred.CredentialName -CommandText $sqlText2

Executar a tarefa

Para iniciar a tarefa imediatamente, execute o seguinte comando:

Write-Output "Start a new execution of the job..."
$jobExecution = $job | Start-AzSqlElasticJob
$jobExecution

Após a conclusão bem-sucedida, você verá duas novas tabelas no , e apenas uma nova tabela no TargetDb1TargetDb2.

Você também pode agendar o trabalho para ser executado mais tarde.

Importante

Todas as horas de início em trabalhos elásticos estão no fuso horário UTC.

Para agendar uma tarefa para ser executada num momento específico, execute o seguinte comando:

# run every hour starting from now
$job | Set-AzSqlElasticJob -IntervalType Hour -IntervalCount 1 -StartTime (Get-Date) -Enable

Monitorizar o estado das execuções de tarefas

Os fragmentos seguintes obtêm os detalhes de execução da tarefa:

# get the latest 10 executions run
$jobAgent | Get-AzSqlElasticJobExecution -Count 10

# get the job step execution details
$jobExecution | Get-AzSqlElasticJobStepExecution

# get the job target execution details
$jobExecution | Get-AzSqlElasticJobTargetExecution -Count 2

A tabela a seguir lista os possíveis estados de execução de trabalho:

Condição Description
Criado A execução do trabalho acabou de ser criada e ainda não está em andamento.
Em curso A execução do trabalho está atualmente em andamento.
EsperandoForRetry A execução do trabalho não foi capaz de concluir sua ação e está esperando para tentar novamente.
Bem sucedido A execução do trabalho foi concluída com êxito.
SucceededWithSkipped A execução do trabalho foi concluída com sucesso, mas alguns de seus filhos foram ignorados.
Falhado A execução do trabalho falhou e esgotou as suas tentativas.
Tempo Limite A execução do trabalho atingiu o tempo limite.
Cancelado A execução do trabalho foi cancelada.
Ignorado A execução do trabalho foi ignorada porque outra execução da mesma etapa do trabalho já estava sendo executada no mesmo destino.
EsperandoForChildJobExecutions A execução do trabalho está aguardando a conclusão de suas execuções filhas.

Clean up resources (Limpar recursos)

Elimine os recursos do Azure criados neste tutorial ao eliminar o grupo de recursos.

Gorjeta

Se você planeja continuar a trabalhar com esses trabalhos, não limpa os recursos criados neste artigo.

Remove-AzResourceGroup -ResourceGroupName $resourceGroupName

Próximo passo

Criar e gerenciar trabalhos elásticos usando T-SQL (visualização)