Invoke-SqlNotebook

模块:

SQLServer

执行 SQL Notebook 文件（.ipynb）并输出具体化笔记本。

语法

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]
      [-ProgressAction <ActionPreference>]
      [<CommonParameters>]

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

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

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

说明

Invoke-SqlNotebook cmdlet 执行 SQL Notebook 文件（.ipynb），并输出具体化的笔记本。

笔记本将在提供的 ServerInstance 和 Database 上执行。

运行 cmdlet 时，生成的 Notebook 文件将位于用户定义的位置或输入笔记本文件的同一目录中。

可以省略 cmdlet outfile：如果是这样，将使用输入文件名创建该 cmdlet 输出文件，并将 _out 追加到该文件中。

示例

示例 1：针对本地服务器执行笔记本（默认实例）

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，具体化笔记本将保存在磁盘上，其名称与 InputFile 相同，_out 作为文件名后缀（notebook.ipynb -> notebook_out.ipynb）

示例 2：在本地服务器上执行笔记本（defaut 实例），并将具体化笔记本保存到指定文件

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。 在此示例中，SQL Server 实例的 NetName 属性将包含在输出文件的名称中;具体化笔记本将用年月-日-小时分钟时间戳。

示例 5：执行 Notebook，在 Azure Data Studio 中打开结果

从 Azure Data Studio 市场 安装 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：执行 Notebook、使用服务主体连接到 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 身份验证的替代方法。

例如，这可用于使用 Service Principal 或 Managed Identity 连接到 SQL Azure DB 和 SQL Azure Managed Instance（请参阅此页面底部的引用）

在常见情况下，使用类似于 (Get-AzAccessToken -ResourceUrl https://database.windows.net).Token（需要 Az.Account 模块）获取此参数

使用此参数时，请勿指定 UserName、Password或 Credential。

类型:	PSObject
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ConnectionString

指定要连接到服务器的连接字符串。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Credential

用于连接到 SQL 实例的用户名和密码字段的 PSCredential 对象。

类型:	PSCredential
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Database

此 cmdlet 连接到 ServerInstance 参数中指定的实例中的此数据库。

类型:	Object
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 将具体化笔记本写入文件时，将执行检查以防止用户意外覆盖现有文件。 使用 -Force 绕过此检查并允许 cmdlet 覆盖现有文件。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-HostNameInCertificate

用于验证 SQL Server TLS/SSL 证书的主机名。

此参数是模块 v22 中的新增参数。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-InputFile

指定将通过 cmdlet 执行的 Notebook 文件 （.ipynb）。

类型:	Object
Position:	Named
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-InputObject

将 Notebook 指定为 Json 字符串，该字符串将用作输入笔记本。

类型:	Object
Position:	Named
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-OutputFile

指定将保存执行笔记本的所需输出笔记本文件。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Password

指定在 Username 参数中指定的 SQL Server 身份验证登录 ID 的密码。

密码区分大小写。 如果可能，请使用 Windows 身份验证，或考虑改用 -Credential 参数。

如果指定密码参数后跟密码，则任何可以看到监视器的用户都可以看到密码。

如果在 .ps1 脚本中编码密码后跟密码，则读取脚本文件的任何人都可以看到密码。

将适当的 NTFS 权限分配给该文件，以防止其他用户能够读取该文件。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ProgressAction

确定 PowerShell 如何响应脚本、cmdlet 或提供程序生成的进度更新，例如由 Write-Progress cmdlet 生成的进度栏。 Write-Progress cmdlet 创建显示命令状态的进度栏。

类型:	ActionPreference
别名:	proga
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ServerInstance

指定一个字符串或 SQL Server 管理对象（SMO）对象，该对象指定数据库引擎实例的名称。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-TrustServerCertificate

指示通道是否在绕过证书链以验证信任的同时进行加密。

在模块的 v22 中，默认为 $true（为了与 v21 兼容）。 在模块的 v23+ 中，默认值将为“$false”，这可能会为现有脚本创建中断性变更。

此参数是模块 v22 中的新增参数。

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Username

指定用于与数据库引擎实例建立 SQL Server 身份验证连接的登录 ID。

密码必须通过 Password 参数指定。

如果未指定用户名和密码，则此 cmdlet 会尝试使用运行 Windows PowerShell 会话的 Windows 帐户进行 Windows 身份验证连接。 如果可能，请使用 Windows 身份验证。

类型:	Object
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

输入

System.Object

System.Management.Automation.PSCredential

输出

System.Object

备注

可视化具体化笔记本的好方法是使用 Azure Data Studio。

相关链接

• Azure Data Studio 中的 SQL Notebook
• PowerShell 扩展
• SQLServer_Cmdlets
• 服务主体
• 托管标识