SqlPackage Extract 參數與屬性

  • 發行項

SqlPackage Extract 動作會在 DACPAC 檔案 (.dacpac) 中建立連線資料庫的結構描述。 根據預設，資料不會包含在 .dacpac 檔案中。 若要包含資料，請使用 Export 動作或使用 Extract 屬性 ExtractAllTableData/TableData。

注意

雖然 Microsoft Entra ID 是 Azure Active Directory (Azure AD) 的新名稱，但為了防止中斷現有的環境，Azure AD 仍會保留在某些硬式編碼元素中，例如 UI 字段、連線提供者、錯誤碼和 Cmdlet。 在本文中，這兩個名稱是可互換的。

命令列語法

SqlPackage 會使用命令列上指定的參數、屬性和 SQLCMD 變數來起始指定的動作。

SqlPackage /Action:Extract {parameters} {properties}

注意

當擷取含有密碼認證 (例如，SQL 驗證使用者) 的資料庫時，該密碼會取代為具有適當複雜性的不同密碼。 SqlPackage 或 DacFx 使用者應該在發佈 Dacpac 之後變更密碼。

範例

# 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;"

Extract 動作的參數

參數 簡短形式 值 描述
/AccessToken: /at: {string} 根據要在連線到目標資料庫時使用的驗證存取權杖，來指定權杖。
/Action: /a: Extract 指定要執行的動作。
/AzureCloudConfig： /acc: {string} 指定用於連線至 Microsoft Entra ID 的自訂端點，格式為：AzureActiveDirectoryAuthority={value};DatabaseServicePrincipalName={value}"。
/Diagnostics: /d: {True|False} 指定診斷記錄是否輸出到主控台。 預設為 False。
/DiagnosticsFile: /df: {string} 指定要儲存診斷記錄的檔案。
/MaxParallelism: /mp: {int} 指定針對資料庫執行之並行作業的平行處理原則的程度。 預設值為 8。
/OverwriteFiles: /of: {True|False} 指定 SqlPackage 是否應該覆寫現有的檔案。 指定 False 會導致 SqlPackage 在遇到現有的檔案時中止動作。 預設值是 True。
/Properties: /p: {PropertyName}={Value} 指定動件專用屬性的名稱/值對：{PropertyName}={Value}。
/Quiet: /q: {True|False} 指定是否隱藏詳細的意見反應。 預設為 False。
/SourceConnectionString: /scs: {string} 指定對來源資料庫有效的 SQL Server/Azure 連接字串。 如果指定了此參數，就應該以獨佔方式將其用於所有其他來源參數。
/SourceDatabaseName: /sdn: {string} 定義來源資料庫的名稱。
/SourceEncryptConnection: /sec: {Optional|Mandatory|Strict|True|False} 指定 SQL 加密是否應該用於來源資料庫連接。 預設值是 True。
/SourceHostNameInCertificate： /shnic: {string} 指定使用 TLS 加密通訊層時，用來驗證來源 SQL Server TLS/SSL 憑證的值。
/SourcePassword: /sp: {string} 若為 SQL Server 驗證案例，則定義要用來存取來源資料庫的密碼。
/SourceServerName： /ssn: {string} 定義裝載來源資料庫的伺服器名稱。
/SourceTimeout: /st: {int} 指定建立來源資料庫連線的逾時 (以秒為單位)。
/SourceTrustServerCertificate: /stsc: {True|False} 指定是否要使用 TLS 來加密來源資料庫連線並且略過驗證信任的憑證鏈結。 預設值為 False。
/SourceUser: /su: {string} 若為 SQL Server 驗證案例，則定義要用來存取來源資料庫的 SQL Server 使用者。
/TargetFile: /tf: {string} 指定本機儲存體中作為動作目標使用的目標檔案 (即 .dacpac 檔案)，而非資料庫。 如果使用此參數，其他目標參數都應該無效。 這個參數對僅支援資料庫目標的動作而言應無效。
/TenantId: /tid: {string} 代表 Microsoft Entra 租用戶 ID 或網域名稱。 支援來賓或匯入的 Microsoft Entra 使用者以及 outlook.com、hotmail.com 或 live.com 等 Microsoft 帳戶時，這是必要選項。 假設已驗證使用者是此租用戶的原生使用者，則若省略此參數，即會使用 Microsoft Entra ID 的預設租用戶 ID。 不過，在此情況下，不支援任何來賓或匯入的使用者及/或在此 Microsoft Entra ID 中託管的 Microsoft 帳戶，且作業會失敗。
如需詳細資訊，請參閱通用驗證搭配 SQL Database 和 Azure Synapse Analytics (適用於 MFA 的 SSMS 支援)。
/ThreadMaxStackSize： /tmss: {int} 指定執行 SqlPackage 動作之執行緒的大小上限 (以 MB 為單位)。 只有在剖析非常大的 Transact-SQL 陳述式時發生堆疊溢位例外狀況，才應該使用此選項。
/UniversalAuthentication: /ua: {True|False} 指定是否應該使用通用驗證。 設定為 True 時，即會啟用支援 MFA 的互動式驗證通訊協定。 此選項也可以用於不使用 MFA 的 Microsoft Entra 驗證，使用需要使用者輸入其使用者名稱和密碼或整合式驗證 (Windows 認證) 的互動式通訊協定。 當 /UniversalAuthentication 設定為 True 時，SourceConnectionString (/scs) 中不能指定任何 Microsoft Entra 驗證。 當 /UniversalAuthentication 設定為 False 時， SourceConnectionString (/scs) 中必須指定 Microsoft Entra 驗證。
如需詳細資訊，請參閱通用驗證搭配 SQL Database 和 Azure Synapse Analytics (適用於 MFA 的 SSMS 支援)。

Extract 動作的特定屬性

屬性 數值 描述
/p: AzureSharedAccessSignatureToken=(STRING) Azure 共用存取簽章 (SAS) 權杖。 請參閱適用於 Azure Synapse Analytics 的 SqlPackage 和使用 Parquet 檔案中資料的 SqlPackage。
/p: AzureStorageBlobEndpoint=(STRING) Azure Blob 儲存體端點。 請參閱適用於 Azure Synapse Analytics 的 SqlPackage 和使用 Parquet 檔案中資料的 SqlPackage。
/p: AzureStorageContainer=(STRING) Azure Blob 儲存體容器。 請參閱適用於 Azure Synapse Analytics 的 SqlPackage 和使用 Parquet 檔案中資料的 SqlPackage。
/p: AzureStorageKey=(STRING) Azure 儲存體帳戶金鑰。 請參閱適用於 Azure Synapse Analytics 的 SqlPackage 和使用 Parquet 檔案中資料的 SqlPackage。
/p: AzureStorageRootPath=(STRING) 容器內的儲存體根路徑。 如果沒有這個屬性，路徑會預設為 servername/databasename/timestamp/。 請參閱適用於 Azure Synapse Analytics 的 SqlPackage 和使用 Parquet 檔案中資料的 SqlPackage。
/p: CommandTimeout=(INT32 '60') 以秒為單位指定對 SQL Server 執行查詢時的命令逾時。
/p: CompressionOption=({Normal|Maximum|Fast|SuperFast|NotCompressed} 'Normal') 指定壓縮的類型。
/p: DacApplicationDescription=(STRING) 定義要儲存在 DACPAC 中繼資料中的應用程式描述。
/p: DacApplicationName=(STRING) 定義要儲存在 DACPAC 中繼資料中的應用程式名稱。 預設值為資料庫名稱。
/p: DacMajorVersion=(INT32 '1') 定義要儲存在 DACPAC 中繼資料中的主要版本。
/p: DacMinorVersion=(INT32 '0') 定義要儲存在 DACPAC 中繼資料中的次要版本。
/p: DatabaseLockTimeout=(INT32 '60') 指定對 SQLServer 執行查詢時的資料庫鎖定逾時 (秒)。 使用 -1 表示永遠等候。
/p: ExtractAllTableData=(BOOLEAN 'False') 指出是否已解壓縮所有使用者資料表中的資料。 如為 'true'，則會解壓縮所有使用者資料表中的資料，且您不能指定解壓縮個別的使用者資料表資料。 如為 'false'，請指定一或多個要解壓縮其資料的使用者資料表。
/p: ExtractApplicationScopedObjectsOnly=(BOOLEAN 'True') 如果為 true，則只擷取指定之來源的應用程式範圍物件。 如果為 false，則擷取指定之來源的所有物件。
/p: ExtractReferencedServerScopedElements=(BOOLEAN 'True') 如果為 true，則擷取來源資料庫物件所參考的登入、伺服器稽核及認證物件。
/p: ExtractTarget=({DacPac|File|Flat|ObjectType|Schema|SchemaObjectType} 'DacPac') 指定資料庫結構描述的替代輸出格式，預設值為 'DacPac'，可輸出 .dacpac 單一檔案。 其他選項會輸出依 'SchemaObjectType' (每個結構描述和物件類型的資料夾中的檔案)、'Schema' (每個結構描述資料夾中的檔案)、'ObjectType' (每個物件類型的資料夾中的檔案)、'Flat' (相同資料夾中的所有檔案) 或 'File' (1 個單一檔案) 整理的一個或多個 .sql 檔案。
/p: ExtractUsageProperties=(BOOLEAN 'False') 指定是否會從資料庫擷取用法屬性，例如資料表資料列計數和索引大小。
/p: HashObjectNamesInLogs=(BOOLEAN 'False') 指定是否要以隨機雜湊值取代記錄中的所有物件名稱。
/p: IgnoreExtendedProperties=(BOOLEAN 'False') 指定是否應該忽略擴充屬性。
/p: IgnorePermissions=(BOOLEAN 'True') 指定是否應該忽略權限。
/p: IgnoreUserLoginMappings=(BOOLEAN 'False') 指定是否忽略使用者與登入之間的關聯性。
/p: LongRunningCommandTimeout=(INT32 '0') 以秒為單位指定對 SQL Server 執行查詢時的長時間執行命令逾時。 使用 0 表示永遠等候。
/p: Storage=({File|Memory}) 指定支援儲存體的類型，以供結構描述模型在擷取期間使用。 'Memory'是 SqlPackage 的 .NET Core 版本的預設值。 'File' 僅適用於 .NET Framework 版本的 SqlPackage，且為預設值。
/p: TableData=(STRING) 指出要解壓縮其資料的資料表。 下列列格式指定資料表名稱，名稱部分使用或不用括弧括住：schema_name.table_identifier。 此屬性可多次指定以顯示多個選項。 適用於擷取至 .dacpac 和 Parquet 檔案的資料。
/p: TempDirectoryForTableData=(STRING) 指定在寫入套件檔案之前，用於緩衝資料表資料的暫存目錄。
/p: VerifyExtraction=(BOOLEAN 'False') 指定是否應驗證擷取的結構描述模型。

後續步驟