Write-SqlTableData

模組:: SqlServer Module

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

語法

ByPath (預設值)

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

ByName

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

ByObject

Write-SqlTableData
    [-InputObject] <Table[]>
    -InputData <PSObject>
    [-Force]
    [-Passthru]
    [-Timeout <Int32>]
    [-AccessToken <PSObject>]
    [-TrustServerCertificate]
    [-HostNameInCertificate <String>]
    [-Encrypt <String>]
    [<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 會將資料 MyDatabase.dbo.TaskManagerDump 寫入上的 MyServer\MyInstance。因為您指定 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。

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

範例 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，而後者可以執行大量插入（這比逐列插入的數據列更有效能）

範例 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 驗證的替代方案。

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

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

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

參數屬性

類型:	PSObject
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ConnectionTimeout

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

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ConnectToDatabase

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Credential

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

參數屬性

類型:	PSCredential
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-DatabaseName

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

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Encrypt

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

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

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

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

參數屬性

類型:	String
預設值:	None
接受的值:	Mandatory, Optional, Strict
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Force

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

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-HostNameInCertificate

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

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-IgnoreProviderContext

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InputData

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

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

參數屬性

類型:	PSObject
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	True
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-InputObject

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

參數屬性

類型:	Table[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByObject

Position:	1
必要:	True
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Passthru

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Path

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

參數屬性

類型:	String[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByPath

Position:	1
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SchemaName

指定數據表的架構名稱。

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

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-ServerInstance

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

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

參數屬性

類型:	String[]
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	1
必要:	False
來自管線的值:	True
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-SuppressProviderContextWarning

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TableName

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

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

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

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

ByName

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-Timeout

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

參數屬性

類型:	Int32
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

-TrustServerCertificate

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

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

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

參數屬性

類型:	SwitchParameter
預設值:	None
支援萬用字元:	False
不要顯示:	False

參數集

(All)

Position:	Named
必要:	False
來自管線的值:	False
來自管線按屬性名稱的值:	False
來自剩餘引數的值:	False

CommonParameters

此 Cmdlet 支援一般參數：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。如需詳細資訊，請參閱 about_CommonParameters。

共用方式為

Write-SqlTableData

語法

ByPath (預設值)

ByName

ByObject

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

參數屬性

參數集

-SchemaName

參數屬性

參數集

-ServerInstance

參數屬性

參數集

-SuppressProviderContextWarning

參數屬性

參數集

-TableName

參數屬性

參數集

-Timeout

參數屬性

參數集

-TrustServerCertificate

參數屬性

參數集

CommonParameters

輸入

System.Management.Automation.PSObject

System.String

Microsoft.SqlServer.Management.Smo.Table

相關連結

意見反應