Delen via

Elastische taken maken en beheren met behulp van PowerShell (preview)

  • Artikel

Van toepassing op: Azure SQL Database

Dit artikel bevat een zelfstudie en voorbeelden om aan de slag te gaan met elastische taken met behulp van PowerShell. Elastisc Jobs maken het mogelijk om één of meerdere T-SQL-scripts (Transact-SQL) parallel in veel databases uit te voeren.

In deze end-to-end zelfstudie leert u de stappen die nodig zijn om een query uit te voeren op meerdere databases:

  • Een elastische taakagent maken
  • Taakreferenties maken zodat taken scripts kunnen uitvoeren op de doelen ervan
  • Definieer de doelen (servers, elastische pools, databases) waarop u de taak wilt uitvoeren
  • Databasereferenties maken in de doeldatabases, zodat de agent verbinding maakt en taken uitvoert
  • Een taak maken
  • Taakstappen toevoegen aan een taak
  • Uitvoering van een taak starten
  • Een taak bewaken

Notitie

Elastische taken zijn in preview. Functies die momenteel in de preview-versie beschikbaar zijn, zijn beschikbaar onder aanvullende gebruiksvoorwaarden. Bekijk de juridische voorwaarden die van toepassing zijn op Azure-functies die in preview zijn. Azure SQL Database biedt previews om u de kans te geven feedback te evalueren en te delen met de productgroep over functies voordat deze algemeen beschikbaar worden.

Vereisten

Elastische databasetaken hebben een set PowerShell-cmdlets.

Deze cmdlets zijn in november 2023 bijgewerkt.

De meest recente cmdlets voor elastische taken installeren

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Als deze nog niet aanwezig is, installeert u de nieuwste versies van de Az.Sql en SqlServer modules. Voer de volgende opdrachten met beheerderstoegang uit in PowerShell.

# 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

Zie SQL Server PowerShell-module installeren voor meer informatie.

Vereiste resources maken

Voor het maken van een elastische-taakagent is een database (S1 of hoger) vereist voor gebruik als de elastische taakdatabase.

Met het volgende script maakt u een nieuwe resourcegroep, server en database voor gebruik als de elastische taakdatabase. Het tweede script maakt een tweede server met twee lege databases om taken op uit te voeren.

Elastische taken hebben geen specifieke naamgevingsvereisten, zodat u de gewenste naamconventies kunt gebruiken, zolang deze voldoen aan alle Azure-vereisten. Als u al een lege database naar de server hebt gemaakt als de elastische-taakdatabase, gaat u verder met het maken van de elastische-taakagent.

Het configureren van een firewallregel met New-AzSqlServerFirewallRule is niet nodig wanneer u een privé-eindpunt voor elastische taken gebruikt.

# 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

De elastische-taakagent maken

Een elastische-taakagent is een Azure-resource voor het maken, uitvoeren en beheren van taken. De agent voert taken uit op basis van een planning of als eenmalige taak. Alle datums en tijden in elastische taken bevinden zich in de UTC-tijdzone.

De cmdlet New-AzSqlElasticJobAgent vereist dat er al een database in Azure SQL Database bestaat, dus de resourceGroupName, serverNameen databaseName parameters moeten allemaal verwijzen naar bestaande resources. Op dezelfde manier kan Set-AzSqlElasticJobAgent worden gebruikt om de elastische taakagent te wijzigen.

Als u een nieuwe elastische-taakagent wilt maken met behulp van Microsoft Entra-verificatie met een door de gebruiker toegewezen beheerde identiteit, gebruikt u de IdentityType en IdentityID argumenten van 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

Als u een nieuwe elastische-taakagent wilt maken met behulp van referenties in databasebereik, IdentityType en IdentityID deze niet worden opgegeven.

De taakverificatie maken

De elastische taakagent moet kunnen worden geverifieerd bij elke doelserver of -database.

Zoals beschreven in verificatie van taakagent maken:

  • Gebruik databasegebruikers die zijn toegewezen aan door de gebruiker toegewezen beheerde identiteit (UMI) om te verifiëren bij de doelserver(s)/database(s).
    • Het gebruik van een UMI met Microsoft Entra-verificatie (voorheen Azure Active Directory) is de aanbevolen methode. PowerShell-cmdlets hebben nu nieuwe argumenten ter ondersteuning van Microsoft Entra-verificatie met een UMI.
    • Dit is de aanbevolen verificatiemethode.
  • Gebruik databasegebruikers die zijn toegewezen aan referenties in databasebereik in elke database.
    • Voorheen waren referenties binnen het databasebereik de enige optie voor de elastische taakagent om te verifiëren bij doelen.

Microsoft Entra-verificatie gebruiken met een UMI voor verificatie op doelen

Volg deze stappen om de aanbevolen methode van Microsoft Entra-verificatie (voorheen Azure Active Directory) te gebruiken voor een door de gebruiker toegewezen beheerde identiteit (UMI). De elastische taakagent maakt verbinding met de gewenste logische doelserver(s)/databases via Entra-verificatie.

Naast de aanmeldings- en databasegebruikers moet u rekening houden met de toevoeging van de GRANT opdrachten in het volgende script. Deze machtigingen zijn vereist voor het script dat we hebben gekozen voor deze voorbeeldtaak. Voor uw taken zijn mogelijk andere machtigingen vereist. Omdat in het voorbeeld een nieuwe tabel in de doeldatabases wordt gemaakt, heeft de databasegebruiker in elke doeldatabase de juiste machtigingen nodig om te kunnen worden uitgevoerd.

Maak in elk van de doelserver(s)/database(s) een ingesloten gebruiker die is toegewezen aan de UMI.

  • Als de elastische taak logische server- of pooldoelen heeft, moet u de ingesloten gebruiker maken die is toegewezen aan de UMI in de master database van de logische doelserver.
  • Als u bijvoorbeeld een ingesloten databaseaanmelding in de master database en een gebruiker in de gebruikersdatabase wilt maken, op basis van de door de gebruiker toegewezen beheerde identiteit (UMI) met de naam 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
}

Databasereferenties gebruiken voor verificatie voor doelen

Jobagents gebruiken referenties die zijn opgegeven door de doelgroep bij het uitvoeren en uitvoeren van scripts. Deze databasereferenties worden ook gebruikt om verbinding te maken met de master database om alle databases op een server of een elastische pool te detecteren wanneer een van deze wordt gebruikt als het type doelgroeplid.

De referenties voor het databasebereik moeten worden gemaakt in de taakdatabase. Alle doeldatabases moeten een aanmelding met voldoende machtigingen hebben om de taak te kunnen voltooien.

Naast de referenties in de afbeelding, moet u rekening houden met de toevoeging van de GRANT opdrachten in het volgende script. Deze machtigingen zijn vereist voor het script dat we hebben gekozen voor deze voorbeeldtaak. Voor uw taken zijn mogelijk andere machtigingen vereist. Omdat in het voorbeeld een nieuwe tabel in de doeldatabases wordt gemaakt, heeft de databasegebruiker in elke doeldatabase de juiste machtigingen nodig om te kunnen worden uitgevoerd.

De aanmelding/gebruiker op elke doelserver/database moet dezelfde naam hebben als de identiteit van de referentie in het databasebereik voor de taakgebruiker en hetzelfde wachtwoord als de referentie in het databasebereik voor de taakgebruiker. Gebruik hetzelfde wachtwoord als het PowerShell-script <strong jobuser password here>gebruikt.

In het volgende voorbeeld worden referenties voor databasebereik gebruikt. Als u de vereiste taakreferenties (in de taakdatabase) wilt maken, voert u het volgende script uit, waarbij SQL-verificatie wordt gebruikt om verbinding te maken met de doelserver(s)/database(s):

# 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

Doelservers en -databases definiëren

Een doelgroep definieert een verzameling van een of meer databases waarop een taakstap wordt uitgevoerd.

Met het volgende codefragment worden twee doelgroepen gemaakt: serverGroupen serverGroupExcludingDb2. serverGroup is gericht op alle databases die aanwezig zijn op de server op het moment van uitvoering en serverGroupExcludingDb2 is gericht op alle databases op de server, met uitzondering van 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

Een taak en stappen maken

In dit voorbeeld worden een taak en twee taakstappen gedefinieerd voor de taak die moet worden uitgevoerd. Met de eerste taakstap (step1) maakt u een nieuwe tabel (Step1Table) in elke database in de doelgroep ServerGroup. Met de tweede taakstap (step2) maakt u een nieuwe tabel (Step2Table) in elke database, met uitzondering van TargetDb2, omdat de doelgroep die eerder is gedefinieerd om deze uit te sluiten.

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

De taak uitvoeren

Voer de volgende opdracht uit om de taak onmiddellijk te starten:

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

Nadat de voltooiing is voltooid, ziet u twee nieuwe tabellen in TargetDb1en slechts één nieuwe tabel in TargetDb2.

U kunt ook plannen dat de taak later wordt uitgevoerd.

Belangrijk

Alle begintijden in elastische taken bevinden zich in de UTC-tijdzone.

Voer de volgende opdracht uit om een ​​taak te plannen die op een specifiek tijdstip moet worden uitgevoerd:

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

Status van taakuitvoeringen bewaken

Met de volgende codefragmenten worden gegevens opgehaald over de taakuitvoering:

# 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

De volgende tabel laat de mogelijke statussen voor taakuitvoering zien:

Toestand Beschrijving
Gemaakt De taakuitvoering is zojuist aangemaakt maar wordt nog niet uitgevoerd.
Wordt uitgevoerd De taak wordt op dit moment uitgevoerd.
Wachten op nieuwe poging De uitvoering van de taak kan de actie niet voltooien en wacht tot het opnieuw wordt geprobeerd.
Geslaagd De taak is succesvol uitgevoerd.
Geslaagd met overgeslagen stukken De taak is succesvol uitgevoerd, maar een aantal onderliggende elementen zijn overgeslagen.
Mislukt De uitvoering van de taak is mislukt en er zijn geen nieuwe pogingen meer over.
Verlopen Er is een time-out opgetreden bij de uitvoering van de taak.
Geannuleerd De uitvoering van de taak is geannuleerd.
Overgeslagen De taakuitvoering is overgeslagen omdat een andere uitvoerbewerking van dezelfde taakstap al op hetzelfde doel werd uitgevoerd.
Wachten op uitvoer van onderliggende elementen De uitvoering van de taak wacht totdat de onderliggende elementen zijn uitgevoerd.

Resources opschonen

Verwijder de Azure-bronnen die in deze zelfstudie zijn gemaakt door de resourcegroep te verwijderen.

Tip

Als u verder wilt werken met deze taken, schoont u de resources die u in dit artikel hebt gemaakt, niet op.

Remove-AzResourceGroup -ResourceGroupName $resourceGroupName

Volgende stap

Elastische taken maken en beheren met behulp van T-SQL (preview)