Invoke-SqlNotebook

模組:

SQLServer

執行 SQL Notebook 檔案 (.ipynb) 並輸出具體化的筆記本。

Syntax

Invoke-SqlNotebook
      [-ServerInstance <Object>]
      [-Database <Object>]
      [-Username <Object>]
      [-Password <Object>]
      [-Credential <PSCredential>]
      [-InputFile <Object>]
      [-InputObject <Object>]
      [-OutputFile <Object>]
      [-AccessToken <PSObject>]
      [-TrustServerCertificate]
      [-Encrypt <String>]
      [-HostNameInCertificate <String>]
      [-Force]
      [<CommonParameters>]

Invoke-SqlNotebook
      [-ConnectionString <Object>]
      [-InputFile <Object>]
      [-InputObject <Object>]
      [-OutputFile <Object>]
      [-Force]
      [<CommonParameters>]

Invoke-SqlNotebook
      -InputFile <Object>
      [-OutputFile <Object>]
      [-Force]
      [<CommonParameters>]

Invoke-SqlNotebook
      -InputObject <Object>
      [-OutputFile <Object>]
      [-Force]
      [<CommonParameters>]

Description

Invoke-SqlNotebook Cmdlet 會執行 SQL Notebook 檔案 (.ipynb) 並輸出具體化的筆記本。

Notebook 將會在提供的 ServerInstance 和 Database 上執行。

執行 Cmdlet 時，產生的 Notebook 檔案將會位於使用者定義的位置，或位於輸入筆記本檔案的相同目錄中。

可以省略 Cmdlet outfile：如果是這種情況，則會使用輸入檔名來建立，並將 _out 附加至檔案。

範例

範例 1：針對本機伺服器執行 Notebook， (預設實例)

PS C:\> Invoke-SqlNotebook -ServerInstance localhost -Database TestNotebook -InputFile C:\notebook.ipynb

   Directory: C:\

Mode           LastWriteTime         Length Name
----           -------------         ------ ----
-a----         8/1/2019  1:00 PM     4656   notebook_out.ipynb

此命令會針對執行 Cmdlet 之機器上執行之 SQL Server 的預設實例執行筆記本。 根據預設，由於未傳入 -OutputFile，具體化筆記本會儲存在磁碟上，其名稱與_out為 filename (notebook.ipynb -> notebook_out.ipynb)

範例 2：在本機伺服器上執行 Notebook (defaut 實例) ，並將具體化的 Notebook 儲存至指定的檔案

PS C:\> Invoke-SqlNotebook -ServerInstance localhost -Database TestNotebook -InputFile C:\notebook.ipynb -OutputFile C:\new_notebook.ipynb

   Directory: C:\

Mode           LastWriteTime         Length Name
----           -------------         ------ ----
-a----         8/1/2019  1:00 PM     44656  new_notebook.ipynb

此命令會針對執行 Cmdlet 之機器上執行之 SQL Server 的預設實例執行筆記本。 然後，執行中的筆記本會儲存至使用 -OutputFile 參數指定的檔案。

範例 3：使用 -ConnectionString 參數執行 Notebook

PS C:\> Invoke-Sqlnotebook -ConnectionString 'Server=Localhost;Database=TestNotebook;Trusted_Connection=True;' -InputFile C:\notebook.ipynb

   Directory: C:\

Mode           LastWriteTime         Length Name
----           -------------         ------ ----
-a----         8/1/2019  1:00 PM     44656  notebook_out.ipynb

這與範例 1 相同，只有透過 -ConnectionString 參數指定與伺服器的連線。

範例 4：對所有已註冊的伺服器執行筆記本

dir 'SQLSERVER:\SQLRegistration\Database Engine Server Group' |
WHERE { $_.Mode -ne 'd'} |            
foreach {
    $datetime = Get-Date -Format yyyyMMddhhmm;
    Get-SqlInstance -ServerInstance $_.Name |
    foreach {
            Invoke-SqlNotebook -ServerInstance $_.Name -Database master -InputFile '$home\Documents\SQL Server Management Studio\BPCheck.ipynb' `
            -OutputFile "BPCheck_output_$($_.NetName)_$($datetime).ipynb";
            }
        }

使用已註冊的伺服器或中央管理伺服器對多部伺服器執行 Invoke-SqlNotebook。 在此範例中，NetNameSQL Server 實例的 屬性將會包含在輸出檔的名稱中;具體化的筆記本將會以年月-日-小時分鐘為單位時間戳。

範例 5：執行 Notebook，在 Azure Data Studio 中開啟結果

從 Azure Data Studio Marketplace 安裝 PowerShell 擴充功能 。 使用 Azure Data Studio 中的 PowerShell 整合式主控台來執行 Invoke-SqlNotebook ，並使用 Open-EditorFile 直接在 Azure Data Studio 中開啟 SQL Notebook 的結果。

Invoke-SqlNotebook -ServerInstance ServerA -Database master -InputFile "$home\Documents\SQL Server Management Studio\BPCheck.ipynb" |
Open-EditorFile

注意：此命令 Open-EditorFile 僅適用於PowerShell整合式主控台。

範例 6：執行筆記本、使用服務主體連線至 (或 受控執行個體) Azure SQL 資料庫

Import-Module SQLServer
Import-Module Az.Accounts -MinimumVersion 2.2.0

### Obtain the Access Token interactively.
### Note: help for Invoke-Sqlcmd has examples on other ways to acquire the token.
Connect-AzAccount
$access_token = (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token

# Now that we have the token, we use it to connect to the database 'mydb' on server 'myserver'
Invoke-SqlNotebook -ServerInstance myserver.database.windows.net -Database master -AccessToken $access_token`
                   -InputFile MyNotebook.ipynb

參數

-AccessToken

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

例如，這可用來連線 SQL Azure DB 和使用 SQL Azure Managed InstanceService Principal 或 Managed Identity (查看此頁面底部的參考)

在常見的案例中，會使用類似 (取得 (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token 此參數，需要 Az.Account 模組)

使用此參數時，請勿指定 UserName、 Password 或 Credential 。

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ConnectionString

指定要連線到伺服器的 連接字串。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Credential

PSCredential 物件，其 [用戶名稱] 和 [密碼] 字段將用來連線到 SQL 實例。

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Database

此 Cmdlet 會連接到 ServerInstance 參數中指定的實例中的這個資料庫。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Encrypt

連接到 SQL Server 時要使用的加密類型。

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

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

這個參數是模組 v22 的新功能。

Type:	String
Accepted values:	Mandatory, Optional, Strict
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Force

根據預設，當 Cmdlet 將具體化筆記本寫入檔案時，會執行檢查以防止使用者意外覆寫現有的檔案。 使用 -Force 略過此檢查並允許 Cmdlet 覆寫現有的檔案。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HostNameInCertificate

用於驗證 SQL Server TLS/SSL 憑證的主機名稱。

這個參數是模組 v22 的新功能。

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InputFile

指定將透過 Cmdlet 執行的 Notebook 檔案 (.ipynb) 。

Type:	Object
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-InputObject

將 Notebook 指定為 Json 字串，做為輸入筆記本。

Type:	Object
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-OutputFile

指定將儲存執行之 Notebook 的所需輸出 Notebook 檔案。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Password

指定 username 參數中指定的 SQL Server 驗證登入標識碼的密碼。

密碼會區分大小寫。 可能的話，請使用 Windows 驗證，或改用 -Credential 參數。

如果您指定 Password 參數後面接著密碼，則任何可以看到您監視的使用者都能看到密碼。

如果您在 .ps1 文本中編碼密碼後面接著密碼，則讀取腳本檔案的任何人都會看到您的密碼。

請將適當的 NTFS 權限指派給此檔案，防止其他使用者讀取此檔案。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ServerInstance

指定字元字串或 SQL Server 管理物件 (SMO) 物件，指定 Database Engine 實例的名稱。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TrustServerCertificate

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

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

這個參數是模組 v22 的新功能。

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Username

指定用於建立 Database Engine 執行個體之 SQL Server 驗證連接的登入識別碼。

密碼必須透過Password參數指定。

如果未指定 Username 和 Password，此 Cmdlet 會嘗試使用執行 Windows PowerShell 會話的 Windows 帳戶進行 Windows 驗證連線。 盡可能使用 Windows 驗證。

Type:	Object
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

輸入

System.Object

System.Management.Automation.PSCredential

輸出

System.Object

備註

可視化具體化 Notebook 的好方式是使用 Azure Data Studio。

相關連結

• Azure Data Studio 中的 SQL 筆記本
• PowerShell 延伸模組
• SQLServer_Cmdlets
• 服務主體
• 受控識別