Tworzenie zadań elastycznych i zarządzanie nimi przy użyciu programu PowerShell

  • Artykuł

Dotyczy:Azure SQL Database

Ten artykuł zawiera samouczek i przykłady umożliwiające rozpoczęcie pracy z zadaniami elastycznymi przy użyciu programu PowerShell. Zadania elastyczne umożliwiają uruchamianie jednego lub większej liczby skryptów języka Transact-SQL (T-SQL) równolegle w wielu bazach danych.

Z tego kompleksowego samouczka dowiesz się, jak wykonać zapytanie w wielu bazach danych:

  • Tworzenie agenta zadań elastycznych
  • Tworzenie poświadczeń zadań, aby umożliwić wykonywanie przez zadania skryptów na ich elementach docelowych
  • Definiowanie obiektów docelowych (serwerów, elastycznych pul, baz danych), dla których chcesz uruchomić zadanie
  • Tworzenie poświadczeń o zakresie bazy danych w docelowych bazach danych, aby agent łączył się i wykonywał zadania
  • Tworzenie zadania
  • Dodawanie kroków zadania do zadania
  • Rozpoczynanie wykonywania zadania
  • Monitorowanie zadania

Wymagania wstępne

Zadania elastycznej bazy danych mają zestaw poleceń cmdlet programu PowerShell.

Te polecenia cmdlet zostały zaktualizowane w listopadzie 2023 r.

Instalowanie najnowszych poleceń cmdlet zadań elastycznych

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.

Jeśli jeszcze nie istnieje, zainstaluj najnowsze wersje modułów Az.Sql i SqlServer . Uruchom następujące polecenia w programie PowerShell z dostępem administracyjnym.

# 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

Aby uzyskać szczegółowe informacje, zobacz Install SQL Server PowerShell module (Instalowanie modułu usługi SQL Server dla programu PowerShell).

Tworzenie wymaganych zasobów

Utworzenie agenta zadań elastycznych wymaga bazy danych (S1 lub nowszej) do użycia jako elastycznej bazy danych zadań.

Poniższy skrypt tworzy nową grupę zasobów, serwer i bazę danych do użycia jako elastyczną bazę danych zadań. Drugi skrypt tworzy drugi serwer z dwoma pustymi bazami danych do wykonywania zadań.

Zadania elastyczne nie mają określonych wymagań dotyczących nazewnictwa, dzięki czemu można używać dowolnych konwencji nazewnictwa, o ile są one zgodne z dowolnymi wymaganiami platformy Azure. Jeśli utworzono już pustą bazę danych na serwerze jako bazę danych zadań elastycznych, przejdź do sekcji Tworzenie agenta zadań elastycznych.

Konfigurowanie reguły zapory z New-AzSqlServerFirewallRule programem jest niepotrzebne podczas korzystania z prywatnego punktu końcowego zadań elastycznych.

# 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

Tworzenie agenta zadań elastycznych

Agent zadań elastycznych to zasób platformy Azure do tworzenia, uruchamiania i zarządzania zadaniami. Agent wykonuje zadania na podstawie harmonogramu lub jako zadania jednorazowe. Wszystkie daty i godziny zadań elastycznych znajdują się w strefie czasowej UTC.

Polecenie cmdlet New-AzSqlElasticJobAgent wymaga, aby baza danych w usłudze Azure SQL Database już istniała, więc resourceGroupNameparametry , serverNamei databaseName muszą wskazywać wszystkie istniejące zasoby. Podobnie narzędzie Set-AzSqlElasticJobAgent może służyć do modyfikowania agenta zadań elastycznych.

Aby utworzyć nowego agenta zadań elastycznych przy użyciu uwierzytelniania firmy Microsoft Entra z tożsamością zarządzaną przypisaną przez użytkownika, użyj IdentityType argumentów i IdentityID :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

Aby utworzyć nowego agenta zadań elastycznych IdentityType przy użyciu poświadczeń o zakresie bazy danych i IdentityID nie są udostępniane.

Tworzenie uwierzytelniania zadania

Agent zadań elastycznych musi mieć możliwość uwierzytelniania na każdym serwerze docelowym lub bazie danych.

Zgodnie z opisem w temacie Tworzenie uwierzytelniania agenta zadań:

  • Użyj użytkowników bazy danych mapowanych na tożsamość zarządzaną przypisaną przez użytkownika (UMI), aby uwierzytelnić się na serwerach docelowych/bazach danych.
    • Używanie interfejsu użytkownika z uwierzytelnianiem entra firmy Microsoft (dawniej Azure Active Directory) jest zalecaną metodą. Polecenia cmdlet programu PowerShell mają teraz nowe argumenty do obsługi uwierzytelniania w usłudze Microsoft Entra przy użyciu interfejsu użytkownika.
    • Jest to zalecana metoda uwierzytelniania.
  • Użyj użytkowników bazy danych mapowanych na poświadczenia o zakresie bazy danych w każdej bazie danych.
    • Wcześniej poświadczenia o zakresie bazy danych były jedyną opcją dla agenta zadań elastycznych do uwierzytelniania w miejscach docelowych.

Używanie uwierzytelniania entra firmy Microsoft z interfejsem UMI na potrzeby uwierzytelniania do celów

Aby użyć zalecanej metody uwierzytelniania firmy Microsoft Entra (dawniej Azure Active Directory) do tożsamości zarządzanej przypisanej przez użytkownika, wykonaj następujące kroki. Agent zadań elastycznych łączy się z żądanymi docelowymi serwerami logicznymi/bazami danych za pośrednictwem uwierzytelniania Entra.

Oprócz użytkowników logowania i bazy danych zanotuj dodanie GRANT poleceń w poniższym skry skryptzie. Te uprawnienia są wymagane dla skryptu, który wybrano dla tego przykładowego zadania. Zadania mogą wymagać różnych uprawnień. Ponieważ w przykładzie tworzona jest nowa tabela w docelowych bazach danych, użytkownik bazy danych w każdej docelowej bazie danych potrzebuje odpowiednich uprawnień do pomyślnego uruchomienia.

W każdym z serwerów docelowych/baz danych utwórz zawartego użytkownika zamapowanego na interfejs użytkownika.

  • Jeśli zadanie elastyczne ma obiekty docelowe serwera logicznego lub puli, należy utworzyć zawartego użytkownika zamapowanego na interfejs użytkownika w master bazie danych docelowego serwera logicznego.
  • Na przykład aby utworzyć zawarte dane logowania bazy danych w master bazie danych i użytkownika w bazie danych użytkownika, na podstawie tożsamości zarządzanej przypisanej przez użytkownika (UMI) o nazwie 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
}

Używanie poświadczeń o zakresie bazy danych do uwierzytelniania w miejscach docelowych

Agenci zadań używają poświadczeń określonych przez grupę docelową podczas wykonywania i wykonywania skryptów. Te poświadczenia o zakresie bazy danych są również używane do łączenia się z master bazą danych w celu odnajdywania wszystkich baz danych na serwerze lub elastycznej puli, gdy jeden z nich jest używany jako typ elementu członkowskiego grupy docelowej.

Poświadczenia o zakresie bazy danych muszą zostać utworzone w bazie danych zadań. Dla wszystkich docelowych baz danych muszą istnieć poświadczenia o uprawnieniach wystarczających do pomyślnego wykonania zadania.

Oprócz poświadczeń na obrazie zwróć uwagę na dodanie GRANT poleceń w poniższym skry skrygcie. Te uprawnienia są wymagane dla skryptu, który wybrano dla tego przykładowego zadania. Zadania mogą wymagać różnych uprawnień. Ponieważ w przykładzie tworzona jest nowa tabela w docelowych bazach danych, użytkownik bazy danych w każdej docelowej bazie danych potrzebuje odpowiednich uprawnień do pomyślnego uruchomienia.

Nazwa logowania/użytkownik na każdym serwerze docelowym/bazie danych musi mieć taką samą nazwę jak tożsamość poświadczeń o zakresie bazy danych dla użytkownika zadania oraz to samo hasło co poświadczenia w zakresie bazy danych dla użytkownika zadania. W przypadku użycia skryptu <strong jobuser password here>programu PowerShell użyj tego samego hasła.

W poniższym przykładzie użyto poświadczeń o zakresie bazy danych. Aby utworzyć wymagane poświadczenia zadania (w bazie danych zadań), uruchom następujący skrypt, który używa uwierzytelniania SQL do łączenia się z serwerami docelowymi/bazami danych:

# 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

Definiowanie serwerów docelowych i baz danych

Grupa docelowa definiuje zestaw zawierający co najmniej jedną bazę danych, względem której będzie wykonywane zadanie.

Poniższy fragment kodu tworzy dwie grupy docelowe: serverGroup, i serverGroupExcludingDb2. serverGroup jest przeznaczona dla wszystkich baz danych, które istnieją na serwerze w czasie wykonywania, i serverGroupExcludingDb2 dotyczy wszystkich baz danych na serwerze, z wyjątkiem 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

Tworzenie zadania i kroków

W tym przykładzie zdefiniowano zadanie i dwa kroki zadania do uruchomienia. Pierwszy krok zadania () tworzy nową tabelę (step1Step1Table) w każdej bazie danych w grupie ServerGroupdocelowej . Drugi krok zadania () tworzy nową tabelę (step2Step2Table) w każdej bazie danych z wyjątkiem TargetDb2elementu , ponieważ wcześniej określona grupa docelowa została określona do wykluczenia.

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

Uruchamianie zadania

Aby natychmiast uruchomić zadanie, uruchom następujące polecenie:

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

Po pomyślnym zakończeniu powinny zostać wyświetlone dwie nowe tabele w pliku TargetDb1i tylko jedna nowa tabela w pliku TargetDb2.

Możesz również zaplanować uruchomienie zadania później.

Ważne

Wszystkie czasy rozpoczęcia zadań elastycznych znajdują się w strefie czasowej UTC.

Aby zaplanować uruchomienie zadania w określonym czasie, uruchom następujące polecenie:

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

Monitorowanie stanu wykonania zadania

Poniższe fragmenty kodu pobierają szczegóły wykonania zadania:

# 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

W poniższej tabeli wymieniono możliwe stany wykonywania zadania:

Stan opis
Tworzone Wykonanie zadania zostało właśnie utworzone i nie jest jeszcze w toku.
Ruch przychodzący Wykonywanie zadania jest obecnie w toku.
OczekiwanieForRetry Wykonanie zadania nie było w stanie ukończyć swojej akcji i czeka na ponowienie próby.
Powodzenie Wykonanie zadania zostało ukończone pomyślnie.
Powodzenie Zmapowane Wykonanie zadania zostało ukończone pomyślnie, ale niektóre z jego elementów podrzędnych zostały pominięte.
Nie działa Wykonanie zadania nie powiodło się i wyczerpało jego ponawianie prób.
Limit czasu Upłynął limit czasu wykonania zadania.
Anulowane Wykonanie zadania zostało anulowane.
Pominięto Wykonanie zadania zostało pominięte, ponieważ inne wykonanie tego samego kroku zadania było już uruchomione w tym samym obiekcie docelowym.
OczekiwanieForChildJobExecutions Wykonanie zadania oczekuje na ukończenie wykonywania podrzędnych.

Czyszczenie zasobów

Usuń zasoby platformy Azure utworzone w tym samouczku, usuwając grupę zasobów.

Napiwek

Jeśli planujesz kontynuować pracę z tymi zadaniami, nie wyczyścisz zasobów utworzonych w tym artykule.

Remove-AzResourceGroup -ResourceGroupName $resourceGroupName

Następny krok

Tworzenie zadań elastycznych i zarządzanie nimi przy użyciu języka T-SQL