Write-SqlTableData

參考

模組:: SQLServer

將數據寫入 SQL 資料庫的數據表。

語法

Write-SqlTableData
     [-Force]
     -InputData <PSObject>
     [-Passthru]
     [-Timeout <Int32>]
     [[-Path] <String[]>]
     [-AccessToken <PSObject>]
     [-TrustServerCertificate]
     [-HostNameInCertificate <String>]
     [-Encrypt <String>]
     [-ProgressAction <ActionPreference>]
     [<CommonParameters>]

Write-SqlTableData
     [-DatabaseName <String>]
     [-SchemaName <String>]
     [-TableName <String>]
     [-IgnoreProviderContext]
     [-SuppressProviderContextWarning]
     [-Force]
     -InputData <PSObject>
     [-Passthru]
     [-Timeout <Int32>]
     [-ConnectToDatabase]
     [[-ServerInstance] <String[]>]
     [-Credential <PSCredential>]
     [-ConnectionTimeout <Int32>]
     [-AccessToken <PSObject>]
     [-TrustServerCertificate]
     [-HostNameInCertificate <String>]
     [-Encrypt <String>]
     [-ProgressAction <ActionPreference>]
     [<CommonParameters>]

Write-SqlTableData
     [-Force]
     -InputData <PSObject>
     [-Passthru]
     [-Timeout <Int32>]
     [-InputObject] <Table[]>
     [-AccessToken <PSObject>]
     [-TrustServerCertificate]
     [-HostNameInCertificate <String>]
     [-Encrypt <String>]
     [-ProgressAction <ActionPreference>]
     [<CommonParameters>]

Description

Write-SqlTableData Cmdlet 會將數據插入 SQL 資料庫的數據表中。此 Cmdlet 接受下列輸入類型，下列輸出格式：

System.Data.DataSet
System.Data.DataTable
System.Data.DateRow 物件
物件的集合

如果您提供 DataSet，則只會將數據集中的第一個數據表寫入資料庫。

您可以搭配 Windows PowerShell SQL 提供者使用此 Cmdlet。

此 Cmdlet 可以從目前的路徑推斷伺服器、資料庫、架構和數據表等資訊。

此 Cmdlet 預期數據表存在。根據預設，Cmdlet 會將數據附加至該數據表。

如果您指定 Force 參數，Cmdlet 會產生遺漏的物件，其中包括資料庫、數據表架構和數據表本身。此使用方式可讓您將數據快速傳輸至資料庫。 Cmdlet 會從數據推斷數據表的架構。結果可能不是最佳結果。例如，字串會對應至 NVARCHAR（MAX）。

範例

範例 1：將進程的相關信息寫入數據表

PS C:\> (Get-Process | Select-Object -Property Id,ProcessName,StartTime,UserProcessorTime,WorkingSet,Description) |
         Write-SqlTableData -ServerInstance "MyServer\MyInstance" -DatabaseName "MyDatabase" -SchemaName "dbo" -TableName "TaskManagerDump" -Force

這個範例會取得在系統上執行之進程的相關信息，並將它寫入數據表。

目前的 Cmdlet 會將數據寫入 MyServer\MyInstance上的 MyDatabase.dbo.TaskManagerDump。因為您指定 Force 參數，如果資料庫、架構和數據表不存在，則此 Cmdlet 會加以建立。

範例 2：將數據寫入數據表

PS C:\> cd SQLSERVER:\SQL\MyServer\MyInstance\Databases\MyDatabase\Tables
PS SQLSERVER:\SQL\MyServer\MyInstance\Databases\MyDatabase\Tables> $Table = Write-SqlTableData -TableName "KeyValuePairs" -SchemaName "dbo" -InputData @{ cca=10; cac='Hello'; aac=1.2 } -PassThru
PS SQLSERVER:\SQL\MyServer\MyInstance\Databases\MyDatabase\Tables> Read-SqlTableData -InputObject $Table

WARNING: Using provider context. Server = MyServer\MyInstance, Database = [MyDatabase]. 

Key Value
--- -----
aac   1.2
cac Hello
cca    10

第一個命令會將位置變更為 SQLSERVER 提供者中的位置。命令提示字元會反映新位置。如需詳細資訊，請輸入 Get-Help about_Providers。

最後一個命令會使用 Read-SqlTableData Cmdlet 來顯示 $Table 變數的內容。

範例 3：將數據從檔案匯入數據表

PS C:\> ,(Import-Csv -Path ".\a.csv" -Header "Id","Name","Amount") | Write-SqlTableData -ServerInstance "MyServer\MyInstance" -DatabaseName "MyDatabase" -SchemaName "dbo" -TableName "CSVTable" -Force
PS C:\> Read-SqlTableData -ServerInstance "MyServer\MyInstance" -DatabaseName "MyDatabase" -SchemaName "dbo" -TableName "CSVTable"

Id Name  Amount
-- ----  ------
10 AAAA  -1.2
11 BBBB   1.2
12 CCCC  -1.0

The first command imports the contents of a file by using the Import-Csv cmdlet. The file contains the following content:
    
10,AAAA,-1.2
11,BBBB,1.2
12,CCCC,-1.0

此範例會從檔案提示字元完全執行。它無法使用內容資訊。因此，您必須指定所有相關參數。

請注意，在行前使用 “，”：這是強制 PowerShell 將檔案的整個內容直接傳遞至 Write-SqlTableData Cmdlet，而 Cmdlet 接著可以執行大量插入（這比逐列插入的數據列更有效能）

範例 4：從某個實例擷取數據，並推送至另一個實例上的資料庫數據表

PS C:\> (Invoke-Sqlcmd -query "SELECT @@SERVERNAME AS 'ServerName', DB_NAME(dbid) AS 'Database',
                              name, CONVERT(BIGINT, size) * 8 AS 'size_in_kb', filename
                              FROM master..sysaltfiles" `
   -ServerInstance MyServer\MyInstance -database master -OutputAs DataTables) |
   Write-SqlTableData -ServerInstance MyServer\MyOtherInstance -Database ServerStats -SchemaName dbo -TableName DatabasesSizes -Force

這個範例會使用 Invoke-SqlCmd Cmdlet，從一個實例取得資料庫檔案大小的相關信息，並將產生的數據列插入至不同 SQL Server 實例上的資料庫。請注意，雖然此範例會在相同計算機上的 SQL Server 實例之間行動數據，但實例可能位於兩個完全不同的伺服器上。

範例 5：將數據寫入至 Azure SQL Database 的現有數據表（或使用 SQL 驗證的任何資料庫）

Import-Module SqlServer

# Set your connection string to Azure SQL DB.
# If your server is not in Azure, just tweak the 'Data Source' field to point to your server.
# Warning: putting clear text passwords in your scripts is highly discoraged, so instead
# of using "User ID" and "Password" in the connection string, we prompt for the credentials.
$cred = Get-Credential -Message "Enter your SQL Auth credentials"
$cred.Password.MakeReadOnly()

# Get access to the SMO Server object.
$srv = Get-SqlInstance -ServerInstance "<your_server_name>.database.windows.net" -Credential $cred

# Get access to table 'MyTable1' on database 'MyDB'.
# Note: both objects are assumed to exists already.
$db = $srv.Databases["MyDB"]
$table = $db.Tables["MyTable1"]

# Write the first 4 integers into the table.
# Note: 'MyTable1' has a column 'Col1' of type 'int'
Write-SqlTableData -InputData (1..4) -InputObject $table

# Now, we read the data back to verify all went ok.
Read-SqlTableData -InputObject $table

# Output:
#
# Col1
# ----
#   1
#   2
#   3
#   4

此範例示範如何使用 Write-SqlTableData Cmdlet 搭配 SQL 驗證。大部分的程式代碼只是 ADO.Net，而且需要 SMO 重複使用才能建立必要的物件（代表目標數據表的 SMO Table 物件），而此物件會透過 -InputOject 參數傳遞至 Cmdlet。

範例 6：使用 Azure VM 的受控識別，將數據寫入至 Azure SQL Database 的現有數據表。

Import-Module Az.Accounts,SQLServer

# Change these 3 variables to match your configuration.
# The example assumes you have a SQL Azure DB with the AdventureWorksLT sample DB on server sql-240627023957.
$Server = 'sql-240627023957.database.windows.net'
$Database = 'AdventureWorksLT'

# Connect to Azure using the system managed identify of the Azure VM this script is running on...
Add-AzAccount -Identity

# ... and fetch an access token to get to the DB.
$AccessToken = (Get-AzAccessToken -ResourceUrl 'https://database.windows.net').Token

# The assumption here is that the Microsoft Entra Admin on the server granted access
# to the managed identity of the VM by running something like:
#   CREATE USER [<Name of the VM>] FROM EXTERNAL PROVIDER
#   ALTER ROLE db_owner ADD MEMBER [<Name of the VM>]
# on the database ($Database).

# Insert a new record into the SalesLT.ProductDescription table
# Note that we are using -ConnectToDatabase to connect directly to the database, since it is unlikely for the
# managed identity of the VM to have access to anything but such database.
Write-SqlTableData -ServerInstance $Server -Database $Database -AccessToken $AccessToken -SchemaName SalesLT -TableName ProductDescription -InputData @{ Description = 'Hello SQLServer' } -ConnectToDatabase

# Confirm that the new record was successfully added
# Note that -ConnectToDatabase it not necessary in this case, as the connection if done directly to the database.
Read-SqlTableData -ServerInstance $Server -Database $Database -AccessToken $AccessToken -SchemaName SalesLT -TableName ProductDescription -OrderBy ModifiedDate -TopN 1 -ColumnOrderType DESC

# Output:
#
# ProductDescriptionID Description     rowguid                              ModifiedDate
# -------------------- -----------     -------                              ------------
#                 2011 Hello SQLServer f5f43821-aacd-4748-9d14-4a525c6a036b 6/30/2024 10:19:26 AM
#

參數

-AccessToken

用來向 SQL Server 驗證的存取令牌，作為使用者/密碼或 Windows 驗證的替代方案。

例如，這可用來使用 Service Principal 或 Managed Identity來連線到 SQL Azure DB 和 SQL Azure Managed Instance。

要使用的參數可以是字串，表示令牌或 PSAccessToken 物件，如執行 Get-AzAccessToken -ResourceUrl https://database.windows.net所傳回。

此參數是模組 v22 的新功能。

類型:	PSObject
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ConnectionTimeout

指定要在逾時失敗前等候伺服器連線的秒數。逾時值必須是介於 0 到 65534 之間的整數。如果指定了 0，連線嘗試就不會逾時。

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ConnectToDatabase

建立連接時，強制 Cmdlet 使用傳入的資料庫（-DatabaseName）作為初始目錄。此參數對於允許低許可權的用戶連線到現有資料庫的寫入作業可能很有用。 建立資料庫時不要 使用。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Credential

指定連接 SQL Server 的 PSCredential 物件。若要取得認證物件，請使用 Get-Credential Cmdlet。如需詳細資訊，請輸入 Get-Help Get-Credential。

類型:	PSCredential
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-DatabaseName

指定包含數據表的資料庫名稱。

Cmdlet 支援引用值。您不需要引號或逸出特殊字元。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Encrypt

線上到 SQL Server 時要使用的加密類型。

此值會對應至 Microsoft.Data.SqlClient 驅動程式之 SqlConnection 物件上的 Encrypt 屬性 SqlConnectionEncryptOption。

在模組的 v22 中，預設值為 Optional （為了與 v21 相容）。在模組的 v23+ 中，預設值會是「強制」，這可能會為現有的腳本建立重大變更。

此參數是模組 v22 的新功能。

類型:	String
接受的值:	Mandatory, Optional, Strict
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Force

指出此 Cmdlet 會建立遺漏的 SQL Server 物件。其中包括資料庫、架構和數據表。您必須具備適當的認證，才能建立這些物件。

如果您未指定遺漏物件的此參數，Cmdlet 會傳回錯誤。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-HostNameInCertificate

用來驗證 SQL Server TLS/SSL 憑證的主機名。如果您的 SQL Server 實例已啟用強制加密，而且您想要使用主機名/shortname 連線到實例，則必須傳遞此參數。如果省略此參數，則必須將完整功能變數名稱（FQDN）傳遞至 -ServerInstance 才能連線到啟用強制加密的 SQL Server 實例。

此參數是模組 v22 的新功能。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-IgnoreProviderContext

表示此 Cmdlet 不會使用目前的內容來覆寫 ServerInstance、DatabaseName、SchemaName和 TableName 參數的值。如果您未指定此參數，Cmdlet 會盡可能忽略這些參數的值，而不是執行 Cmdlet 的內容。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-InputData

指定要寫入資料庫的數據。

一般輸入數據是 System.Data.DataTable，但您可以指定 System.Data.DataSet 或 System.Data.DateRow* 物件。

類型:	PSObject
Position:	Named
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-InputObject

指定 SQL Server 管理物件（SMO）物件的陣列，代表這個 Cmdlet 寫入的數據表。

類型:	Table[]
Position:	1
預設值:	None
必要:	True
接受管線輸入:	True
接受萬用字元:	False

-Passthru

表示此 Cmdlet 會傳回 SMO。Table 物件。這個物件代表包含已加入數據的數據表。您可以在寫入作業之後在資料表上操作。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Path

指定此 Cmdlet 寫入資料之資料表之 SQL 提供者內容的完整路徑。

類型:	String[]
Position:	1
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ProgressAction

決定 PowerShell 如何回應腳本、Cmdlet 或提供者所產生的進度更新，例如 Write-Progress Cmdlet 所產生的進度列。 Write-Progress Cmdlet 會建立顯示命令狀態的進度列。

類型:	ActionPreference
別名:	proga
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-SchemaName

指定數據表的架構名稱。

如果您在資料庫或資料庫的子項目內容中執行此 Cmdlet，Cmdlet 會忽略此參數值。請為 Cmdlet 指定 IgnoreProviderContext 參數，以無論如何使用 SchemaName 參數的值。

Cmdlet 支援引用值。您不需要引號或逸出特殊字元。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-ServerInstance

指定 SQL Server 實例的名稱。針對預設實例，指定計算機名稱。針對具名實例，請使用 ComputerName\InstanceName格式。

如果您在資料庫或資料庫的子項目內容中執行此 Cmdlet，Cmdlet 會忽略此參數值。請為 Cmdlet 指定 IgnoreProviderContext 參數，以無論如何使用 ServerInstance 參數的值。

類型:	String[]
Position:	1
預設值:	None
必要:	False
接受管線輸入:	True
接受萬用字元:	False

-SuppressProviderContextWarning

指出此 Cmdlet 會隱藏指出 Cmdlet 使用提供者內容的警告訊息。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TableName

指定這個 Cmdlet 讀取所在的資料表名稱。

如果您在資料庫或資料庫的子項目內容中執行此 Cmdlet，Cmdlet 會忽略此參數值。請為 Cmdlet 指定 IgnoreProviderContext 參數，以使用 TableName 參數的值。

Cmdlet 支援引用值。您不需要引號或逸出特殊字元。

類型:	String
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-Timeout

指定寫入作業的逾時值，以秒為單位。如果您未指定值，Cmdlet 會使用預設值（通常是 30 秒）。為了避免逾時，請傳遞0。逾時必須是介於 0 到 65535 之間的整數值。

類型:	Int32
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

-TrustServerCertificate

指出通道是否會在略過憑證鏈結以驗證信任時加密。

在模組的 v22 中，預設值為 $true （為了與 v21 相容）。在模組的 v23+ 中，預設值會是『$false』，這可能會為現有的腳本建立重大變更。

此參數是模組 v22 的新功能。

類型:	SwitchParameter
Position:	Named
預設值:	None
必要:	False
接受管線輸入:	False
接受萬用字元:	False

輸入

System.Management.Automation.PSObject

System.String[]

Microsoft.SqlServer.Management.Smo.Table[]

Read-SqlTableData

共用方式為

Write-SqlTableData

語法

Description

範例

範例 1：將進程的相關信息寫入數據表

範例 2：將數據寫入數據表

範例 3：將數據從檔案匯入數據表

範例 4：從某個實例擷取數據，並推送至另一個實例上的資料庫數據表

範例 5：將數據寫入至 Azure SQL Database 的現有數據表（或使用 SQL 驗證的任何資料庫）

範例 6：使用 Azure VM 的受控識別，將數據寫入至 Azure SQL Database 的現有數據表。

參數

-AccessToken

-ConnectionTimeout

-ConnectToDatabase

-Credential

-DatabaseName

-Encrypt

-Force

-HostNameInCertificate

-IgnoreProviderContext

-InputData

-InputObject

-Passthru

-Path

-ProgressAction

-SchemaName

-ServerInstance

-SuppressProviderContextWarning

-TableName

-Timeout

-TrustServerCertificate

輸入

意見反應

其他資源

共用方式為

Write-SqlTableData

語法

Description

範例

範例 1：將進程的相關信息寫入數據表

範例 2：將數據寫入數據表

範例 3：將數據從檔案匯入數據表

範例 4：從某個實例擷取數據，並推送至另一個實例上的資料庫數據表

範例 5：將數據寫入至 Azure SQL Database 的現有數據表（或使用 SQL 驗證的任何資料庫）

範例 6：使用 Azure VM 的受控識別，將數據寫入至 Azure SQL Database 的現有數據表。

參數

-AccessToken

-ConnectionTimeout

-ConnectToDatabase

-Credential

-DatabaseName

-Encrypt

-Force

-HostNameInCertificate

-IgnoreProviderContext

-InputData

-InputObject

-Passthru

-Path

-ProgressAction

-SchemaName

-ServerInstance

-SuppressProviderContextWarning

-TableName

-Timeout

-TrustServerCertificate

輸入

相關連結

意見反應

其他資源