Parameter und Eigenschaften für die Extract-Aktion von SqlPackage
Mit der Aktion „SqlPackage Extract“ wird ein Schema einer verbundenen Datenbank in einer DACPAC-Datei (.dacpac) erstellt. Standardmäßig sind in der DACPAC-Datei keine Daten enthalten. Verwenden Sie zum Einschließen von Daten die Exportaktion oder die Extraktionseigenschaften ExtractAllTableData/TableData.
Hinweis
Während Microsoft Entra-ID der neue Name für Azure Active Directory (Azure AD) ist, bleibt Azure AD in einigen fest kodierten Elementen wie Benutzeroberfläche-Feldern, Verbindungsanbietern, Fehlercodes und Cmdlets erhalten, um Störungen in bestehenden Umgebungen zu vermeiden. In diesem Artikel sind die beiden Namen austauschbar.
Befehlszeilensyntax
SqlPackage initiiert die angegebenen Aktionen mithilfe der Parameter, Eigenschaften und SQLCMD-Variablen, die in der Befehlszeile angegeben sind.
SqlPackage /Action:Extract {parameters} {properties}
Hinweis
Wenn eine Datenbank mit Kennwortanmeldeinformationen (z. B. ein SQL-Authentifizierungsbenutzer) extrahiert wird, wird das Kennwort durch ein anderes Kennwort mit geeigneter Komplexität ersetzt. SqlPackage- oder DacFx-Benutzer sollten das Kennwort ändern, nachdem die DACPAC-Datei veröffentlicht wurde.
Beispiele
# example extract to create a schema-only .dacpac file connecting using SQL authentication
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=false /p:VerifyExtraction=true \
/SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
# example extract to create a .sql file containing the schema definition of the database
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /SourceServerName:{serverFQDN} \
/SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password} /p:ExtractTarget=File
# example extract to create a .dacpac file with data connecting using SQL authentication
SqlPackage /Action:Extract /TargetFile:{filename}.dacpac /DiagnosticsFile:{logFile}.log /p:ExtractAllTableData=true /p:VerifyExtraction=true \
/SourceServerName:{serverFQDN} /SourceDatabaseName:{databaseName} /SourceUser:{username} /SourcePassword:{password}
# example extract to create a schema-only .dacpac file connecting using Microsoft Entra managed identity
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Managed Identity;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# example extract to create a schema-only .dacpac file connecting using Microsoft Entra username and password
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;Authentication=Active Directory Password;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;User ID={yourusername};Password={yourpassword}"
# example extract to create a schema-only .dacpac file connecting using Microsoft Entra universal authentication
SqlPackage /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" /UniversalAuthentication:True \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# example extract to create a schema-only .dacpac file connecting using an access token associated with a service principal
$Account = Connect-AzAccount -ServicePrincipal -Tenant $Tenant -Credential $Credential
$AccessToken_Object = (Get-AzAccessToken -Account $Account -Resource "https://database.windows.net/")
$AccessToken = $AccessToken_Object.Token
SqlPackage /at:$AccessToken /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
# OR
SqlPackage /at:$($AccessToken_Object.Token) /Action:Extract /TargetFile:"C:\AdventureWorksLT.dacpac" \
/SourceConnectionString:"Server=tcp:{yourserver}.database.windows.net,1433;Initial Catalog=AdventureWorksLT;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
Parameter für die Extract-Aktion
| Parameter | Kurzform | Wert | BESCHREIBUNG |
|---|---|---|---|
| /AccessToken: | /at: | {string} | Gibt das Zugriffstoken für die tokenbasierte Authentifizierung an, das beim Herstellen einer Verbindung mit der Zieldatenbank verwendet werden soll. |
| /Action: | /a: | Extract | Gibt die auszuführende Aktion an. |
| /AzureCloudConfig: | /acc: | {string} | Gibt die benutzerdefinierten Endpunkte zum Herstellen einer Verbindung mit Microsoft Entra im folgenden Format an: AzureActiveDirectoryAuthority={Wert};DatabaseServicePrincipalName={Wert}. |
| /Diagnostics: | /d: | {True|False} | Gibt an, ob die Diagnoseprotokollierung in der Konsole ausgegeben wird. Der Standardwert lautet „False“. |
| /DiagnosticsFile: | /df: | {string} | Gibt eine Datei an, in der Diagnoseprotokolle gespeichert werden. |
| /MaxParallelism: | /mp: | {int} | Gibt den Parallelitätsgrad für gleichzeitige Vorgänge in einer Datenbank an. Der Standardwert ist 8. |
| /OverwriteFiles: | /of: | {True|False} | Gibt an, ob vorhandene Dateien von SqlPackage überschrieben werden sollen. Bei Angabe von FALSE wird die Aktion von SqlPackage abgebrochen, wenn eine vorhandene Datei gefunden wird. Der Standardwert ist TRUE. |
| /Properties: | /p: | {PropertyName}={Value} | Gibt ein Name-Wert-Paar für eine aktionsspezifische Eigenschaft an: {PropertyName}={Value}. |
| /Quiet: | /q: | {True|False} | Gibt an, ob ausführliches Feedback unterdrückt wird. Der Standardwert lautet „False“. |
| /SourceConnectionString: | /scs: | {string} | Gibt eine gültige SQL Server-/Azure-Verbindungszeichenfolge für die Quelldatenbank an. Die Angabe dieses Parameters schließt die Verwendung aller anderen Quellparameter aus. |
| /SourceDatabaseName: | /sdn: | {string} | Definiert den Namen der Quelldatenbank. |
| /SourceEncryptConnection: | /sec: | {Optional|Obligatorisch|Strikt|True|False} | Gibt an, ob für die Verbindung mit der Quelldatenbank die SQL-Verschlüsselung verwendet werden soll. Der Standardwert ist TRUE. |
| /SourceHostNameInCertificate: | /shnic: | {string} | Gibt den Wert an, der verwendet wird, um das TLS/SSL-Zertifikat des Quell-SQL-Servers zu überprüfen, wenn die Kommunikationsebene mit TLS verschlüsselt wird. |
| /SourcePassword: | /sp: | {string} | Definiert in SQL Server-Authentifizierungsszenarios das Kennwort für den Zugriff auf die Quelldatenbank. |
| /SourceServerName: | /ssn: | {string} | Definiert den Namen des Servers, auf dem die Quelldatenbank gehostet wird. |
| /SourceTimeout: | /st: | {int} | Gibt das Timeout in Sekunden für das Herstellen einer Verbindung mit der Quelldatenbank an. |
| /SourceTrustServerCertificate: | /stsc: | {True|False} | Gibt an, ob zum Verschlüsseln der Verbindung mit der Quelldatenbank TLS verwendet und das Durchlaufen der Zertifikatkette zum Überprüfen der Vertrauenswürdigkeit umgangen werden soll. Der Standardwert ist "False". |
| /SourceUser: | /su: | {string} | Definiert in SQL Server-Authentifizierungsszenarios den SQL Server-Benutzer für den Zugriff auf die Quelldatenbank. |
| /TargetFile: | /tf: | {string} | Gibt eine Zieldatei (d. h. eine DACPAC-Datei) im lokalen Speicher an, die anstelle einer Datenbank als Ziel der Aktion verwendet werden soll. Bei Verwendung dieses Parameters sind keine anderen Zielparameter zulässig. Dieser Parameter ist für Aktionen ungültig, die ausschließlich Datenbankziele unterstützen. |
| /TenantId: | /tid: | {string} | Stellt die Microsoft Entra-Mandanten-ID oder den Domänenamen dar. Diese Option ist für die Unterstützung von Gastbenutzern oder importierten Microsoft Entra-Benutzern sowie für Microsoft-Konten wie beispielsweise outlook.com, hotmail.com oder live.com erforderlich. Bei Auslassen dieses Parameters wird die Standardmandanten-ID für Microsoft Entra ID verwendet. Hierbei wird davon ausgegangen, dass der authentifizierte Benutzer ein nativer Benutzer dieses Mandanten ist. In diesem Fall werden jedoch Gastbenutzer oder importierte Benutzer und/oder Microsoft-Konten, die in dieser Microsoft Entra ID gehostet werden, nicht unterstützt, und der Vorgang ist nicht erfolgreich. Weitere Informationen finden Sie unter Universelle Authentifizierung bei SQL-Datenbank und Azure Synapse Analytics (SSMS-Unterstützung für MFA). |
| /ThreadMaxStackSize: | /tmss: | {int} | Gibt die maximale Größe in Megabyte für den Thread an, der die Aktion in SqlPackage ausführt. Diese Option sollte nur verwendet werden, wenn Stapelüberlaufausnahmen festgestellt werden, die beim Analysieren sehr umfangreicher Transact-SQL-Anweisungen auftreten. |
| /UniversalAuthentication: | /ua: | {True|False} | Gibt an, ob die universelle Authentifizierung verwendet werden soll. Bei Festlegung auf TRUE wird das interaktive Authentifizierungsprotokoll aktiviert, das MFA unterstützt. Diese Option kann auch für die Microsoft Entra-Authentifizierung ohne MFA verwendet werden. Hierbei wird ein interaktives Protokoll verwendet, bei dem der Benutzer seinen Benutzernamen und sein Kennwort oder eine integrierte Authentifizierung (Windows-Anmeldeinformationen) eingeben muss. Bei Festlegung von „/UniversalAuthentication“ auf TRUE kann in „SourceConnectionString“ (/scs) keine Microsoft Entra-Authentifizierung angegeben werden. Bei Festlegung von „/UniversalAuthentication“ auf FALSE muss in „SourceConnectionString“ (/scs) die Microsoft Entra-Authentifizierung angegeben werden. Weitere Informationen finden Sie unter Universelle Authentifizierung bei SQL-Datenbank und Azure Synapse Analytics (SSMS-Unterstützung für MFA). |
Spezifische Eigenschaften für die Extract-Aktion
| Eigenschaft | Wert | BESCHREIBUNG |
|---|---|---|
| /p: | AzureSharedAccessSignatureToken=(STRING) | Azure Shared Access Signature (SAS)-Token. Siehe SqlPackage für Azure Synapse Analytics und SqlPackage mit Daten in Parquet-Dateien. |
| /p: | AzureStorageBlobEndpoint=(STRING) | Azure Blob Storage-Endpunkt. Siehe SqlPackage für Azure Synapse Analytics und SqlPackage mit Daten in Parquet-Dateien. |
| /p: | AzureStorageContainer=(STRING) | Azure Blob Storage-Container. Siehe SqlPackage für Azure Synapse Analytics und SqlPackage mit Daten in Parquet-Dateien. |
| /p: | AzureStorageKey=(STRING) | Azure Storage-Kontoschlüssel. Siehe SqlPackage für Azure Synapse Analytics und SqlPackage mit Daten in Parquet-Dateien. |
| /p: | AzureStorageRootPath=(STRING) | Dieser Wert gibt den Azure Storage-Stammpfad innerhalb des Containers an. Ohne diese Eigenschaft lautet der Standardpfad servername/databasename/timestamp/. Siehe SqlPackage für Azure Synapse Analytics und SqlPackage mit Daten in Parquet-Dateien. |
| /p: | CommandTimeout=(INT32 '60') | Gibt das Befehlstimeout in Sekunden zum Ausführen von Abfragen in SQL Server zurück. |
| /p: | CompressionOption=({Normal|Maximum|Fast|SuperFast|NotCompressed} 'Normal') | Gibt den Typ der Komprimierung an. |
| /p: | DacApplicationDescription=(STRING) | Definiert die in den DACPAC-Metadaten zu speichernde Anwendungsbeschreibung. |
| /p: | DacApplicationName=(STRING) | Definiert den in den DACPAC-Metadaten zu speichernden Anwendungsnamen. Der Standardwert entspricht dem Datenbanknamen. |
| /p: | DacMajorVersion=(INT32 '1') | Definiert die in den DACPAC-Metadaten zu speichernde Hauptversion. |
| /p: | DacMinorVersion=(INT32 '0') | Definiert die in den DACPAC-Metadaten zu speichernde Nebenversion. |
| /p: | DatabaseLockTimeout=(INT32 '60') | Gibt das Datenbank-Sperrtimeout für Abfragen an SQL Server in Sekunden an. Verwenden Sie „-1“, um unbegrenzt zu warten. |
| /p: | ExtractAllTableData=(BOOLEAN 'False') | Gibt an, ob Daten aus allen Benutzertabellen extrahiert werden. Bei Festlegung auf TRUE werden Daten aus allen Benutzertabellen extrahiert, und es ist nicht möglich, einzelne Benutzertabellen für das Extrahieren von Daten anzugeben. Bei Festlegung auf FALSE können Sie eine oder mehrere Benutzertabellen zum Extrahieren von Daten angeben. |
| /p: | ExtractApplicationScopedObjectsOnly=(BOOLEAN 'True') | Beim Wert "true" werden nur Objekte im Anwendungsbereich für die angegebene Quelle extrahiert. Beim Wert "false" werden alle Objekte für die angegebene Quelle extrahiert. |
| /p: | ExtractReferencedServerScopedElements=(BOOLEAN 'True') | Beim Wert TRUE werden Anmelde-, Serverüberwachungs- und Anmeldeinformationsobjekte extrahiert, auf die von Quelldatenbankobjekten verwiesen wird. |
| /p: | ExtractTarget=({DacPac|File|Flat|ObjectType|Schema|SchemaObjectType} 'DacPac') | Gibt alternative Ausgabeformate des Datenbankschemas an. Die Standardeinstellung ist „DacPac“ zur Ausgabe einer einzelnen .dacpac-Datei. Zusätzliche Optionen geben eine oder mehrere .sql-Dateien aus, die nach „SchemaObjectType“ (Dateien in Ordnern für jedes Schema und jeden Objekttyp), „Schema“ (Dateien in Ordnern für jedes Schema), „ObjectType“ (Dateien in Ordnern für jeden Objekttyp), „Flat“ (alle Dateien in demselben Ordner) oder „File“ (eine einzige Datei) organisiert werden. |
| /p: | ExtractUsageProperties=(BOOLEAN 'False') | Gibt an, ob Einsatzeigenschaften wie die Anzahl von Tabellenzeilen und Indexgröße aus der Datenbank extrahiert werden. |
| /p: | HashObjectNamesInLogs=(BOOLEAN 'False') | Gibt an, ob alle Objektnamen in Protokollen durch einen zufälligen Hashwert ersetzt werden sollen. |
| /p: | IgnoreExtendedProperties=(BOOLEAN 'False') | Gibt an, ob erweiterte Eigenschaften ignoriert werden sollen. |
| /p: | IgnorePermissions=(BOOLEAN 'True') | Gibt an, ob Berechtigungen ignoriert werden sollen. |
| /p: | IgnoreUserLoginMappings=(BOOLEAN 'False') | Gibt an, ob Beziehungen zwischen Benutzern und Anmeldenamen ignoriert werden. |
| /p: | LongRunningCommandTimeout=(INT32 '0') | Gibt das Timeout für zeitintensive Befehle beim Ausführen von Abfragen an SQL Server in Sekunden zurück. Verwenden Sie „0“, um unbegrenzt zu warten. |
| /p: | Storage=({File|Memory}) | Gibt den Typ des Hintergrundspeichers an, der während der Extraktion für das Schemamodell verwendet wird. „Memory“ ist die Standardeinstellung für die .NET Core-Version von SqlPackage. „File“ ist nur als Standardeinstellung für die .NET Framework-Version von SqlPackage verfügbar. |
| /p: | TableData=(STRING) | Gibt die Tabelle an, aus der Daten extrahiert werden. Geben Sie den Tabellennamen mit oder ohne Klammern um die Namensteile im folgenden Format an: Schemaname.Tabellen-ID. Diese Eigenschaft kann mehrfach angegeben werden, um mehrere Optionen anzuzeigen. Gilt für Daten, die sowohl in .dacpac als auch Parquet-Dateien extrahiert werden. |
| /p: | TempDirectoryForTableData=(STRING) | Gibt das temporäre Verzeichnis an, das zum Puffern von Tabellendaten verwendet wird, bevor diese in die Paketdatei geschrieben werden. |
| /p: | VerifyExtraction=(BOOLEAN 'False') | Gibt an, ob das extrahierte Schemamodell überprüft werden soll. |
Nächste Schritte
- Weitere Informationen zu SqlPackage
- Behandeln von Problemen mit SqlPackage