构建 Concept PowerShell 模块：第 1 部分

本教程将教您如何创建高级函数来与 Notion API 交互。 Notion 是一个功能强大的 Web 应用程序，用于在灵活的工作空间中管理知识。通过 Notion PowerShell 集成将您的自动化提升到新的水平！

先决条件

要按照本教程进行操作，您只需要一个 Notion 帐户和 PowerShell；这里使用的是PowerShell v7.3.7。

创建概念集成令牌

登录 Notion 后，打开浏览器进入“我的集成”页面。在这里，您将创建一个新的集成。生成的密钥将在每个请求中使用，以验证您的 REST API 调用。

1. 进入我的集成页面后，单击“创建新集成”占位符或“+ 新集成”按钮。

2. 接下来，相应地填写详细信息。选择关联工作区并提供名称来标识集成。 （可选）上传徽标以进一步区分您的集成。

3. 单击眼睛图标以显示集成秘密。复制此集成密钥以供以后在 PowserShell 脚本中使用。

4. 导航至功能部分并进行必要的更改，此处使用默认值。

在 PowerShell 中与 Notion API 交互

创建集成并掌握密钥后，导航到您将与之交互的给定页面。您可以授予对一系列页面的顶层或根的集成访问权限。当被授予对一系列页面的根的访问权限时，所有子页面也将可以通过集成访问。

在此示例中，已创建 PowerShell 测试页面。您可以通过单击右上角的三个点来访问其他菜单选项，通过“连接”菜单添加集成访问。突出显示“添加连接”并选择新创建的名为“PowerShell”的集成。 ”

将显示确认信息，并且如上所述，将询问您是否也授予对所有子页面的集成访问权限。

检索页面块

Notion 中的一切都基于块的概念。一个段落被视为一个块，即使是一个空块。由于该页面没有内容，可以请求内容，会返回默认的空段落块。

您将需要几条信息来创建对 Notion 的 REST API 调用。

• API 密钥 - 之前创建的集成和保存的 API 密钥。
• API URI - REST API 的 URL。
• API 版本 - REST API 中可能并且确实会不时发生重大更改。您需要提供您正在操作的 API 版本。在创建本文时，当前版本为 2022-06-28。
• 页面大小 - 您只能在单个 REST API 调用中请求一定数量的块，子块调用的最大值为 100。
• GUID（全球唯一标识符） - 每个 Notion 页面均由其 GUID（友好文本后附加的值）标识。您可以从 URL 复制并粘贴该值。例如，页面为 PowerShell-Testing-a2b3646de9414df4874d56153139b618，但 GUID 为 a2b3646de9414df4874d56153139b618。

?虽然显示了密钥，但它已被删除并且不再有效。

掌握所有这些内容后，就可以创建 REST API 调用了。与 PowerShell 中的大多数 REST API 调用一样，您将调用 Invoke-RestMethod cmdlet。为了便于阅读，参数使用参数展开进行布局，请求结果存储在 $Result 变量中。要查看结果，请在最后请求 results 属性。

$APIKey     = 'secret_fS2A21NwTL4L6XWFTTdgmF3xboWiYXExKZ8Pw15oRMw'
$APIURI     = 'https://api.notion.com/v1'
$APIVersion = '2022-06-28'
$PageSize   = '100'
$GUID       = 'a2b3646de9414df4874d56153139b618'

$Params = @{
    "Headers" = @{
        "Authorization"  = "Bearer {0}" -F $APIKey
        "Content-type"   = "application/json"
        "Notion-Version" = "{0}" -F $APIVersion
    }
    "Method"  = 'GET'
    "URI"     = ("{0}/blocks/{1}/children?page_size={2}" -F $APIURI, [GUID]::new($GUID), $PageSize)
}

$Result = Invoke-RestMethod @Params

$Result.results

正如您所看到的，返回了一个带有详细信息的块。实际内容虽然是空白，但位于 paragraph 属性和 rich_text 属性内。目前，里面什么也没有。

如果文本“Hello from Notion！在测试页面中输入“”，然后重新运行代码，然后返回的 rich_text 值将反映这一点。

创建高级 PowerShell 函数

掌握了基础知识后，下一步是什么？要创建更强大的可重用函数，您可以利用高级 PowerShell 函数的原则。改进之处包括在命令行上运行的代码更少、脚本使用更简单以及验证更多。此外，由于 page_size 限制为 100，超过该限制的页面将需要递归调用来检索所有结果，而此高级函数可以做到这一点。

考虑到意图，代码如何工作？对于任何高级函数，必须在函数声明下包含 [CmdletBinding()]。这向 PowerShell 表明您可以使用高级功能。

接下来，声明 Param 代码块。对于两个参数：$APIURI 和 $GUID，高级验证是通过 ValidateScript 装饰器完成的。使用 [System.URI]::IsWellFormedUriString 方法，可以验证传递的值是否是准确的 URI。 [GUID]::Parse 方法 [GUID] 类型加速器测试传入的值是否为真正的 GUID。

在 Begin 块中，不是在每次迭代时重新定义传递给 Invoke-RestMethod 的参数，而是在管道开始时定义一次。欺骗部分位于 Process 块中。 Notion 的 start_cursor 参数定义了结果收集的开始位置。如果已定义，则将跳过先前的值，并从此处开始计算接下来的 100 块。

在此函数中，仅在递归调用上定义。例如，如果存在超过 100 块，Notion 将返回 true 或 false $Results.has_more 值。如果这是真的，则调用相同的 Get-NotionBlock 函数，通过 $PSBoundParameters 特殊变量传入相同的参数，并给出 $Result.next_cursor 值到 -StartCursor 参数。这将继续这样做，直到 has_more 为 false。

类似地，这就是 has_children 属性的工作原理，因为也可能需要检索子块。该函数将在继续之前调用自身来检索这些内容。

Function Get-NotionBlock {
    [CmdletBinding()]

    Param(
        [String]$APIKey,
        [String]$APIVersion,
        [ValidateScript( { [System.URI]::IsWellFormedUriString( $_ ,[System.UriKind]::Absolute ) } )][String]$APIURI,
        [ValidateScript( { Try { If ( [GUID]::Parse( $_ ) ) { $True } } Catch { $False } } )][String]$GUID,
        [String]$StartCursor,
        [Int]$PageSize = 100
    )

    Begin {
        $Params = @{
            "Headers" = @{
                "Authorization"  = "Bearer {0}" -F $APIKey
                "Content-type"   = "application/json"
                "Notion-Version" = "{0}" -F $APIVersion
            }
            "Method"  = 'GET'
        }
    }

    Process {
        Try {
            If ($StartCursor) {
                $Params.Add("URI" , ("{0}/blocks/{1}/children?start_cursor={3}&page_size={2}" -F $APIURI, [GUID]::new($GUID), $PageSize, $StartCursor))
            } Else {
                $Params.Add("URI" , ("{0}/blocks/{1}/children?page_size={2}" -F $APIURI, [GUID]::new($GUID), $PageSize))
            }

            Write-Verbose "[Process] Params: $($Params | Out-String)"
            
            $Result = Invoke-RestMethod @Params

            If ($Result.has_more) {
                $Result.results

                If ([Bool]($Result.results | Where-Object has_children -EQ $True)) {
                    $Result.results | Where-Object has_children -EQ $True | ForEach-Object { Get-NotionBlock @PSBoundParameters -StartCursor:$Null -GUID $PSItem.id }
                }

                Write-Verbose "[Process] More Results Exist"

                Get-NotionBlock @PSBoundParameters -StartCursor $Result.next_cursor
            } Else {
                $Result.results

                If ([Bool]($Result.results | Where-Object has_children -EQ $True)) {
                    $Result.results | Where-Object has_children -EQ $True | ForEach-Object { Get-NotionBlock @PSBoundParameters -StartCursor:$Null -GUID $PSItem.id }
                }
            }
        } Catch {
            $Message = ($Error[0].ErrorDetails.Message | ConvertFrom-JSON).message

            Write-Error "Command Failed to Run: $Message"
        }
    }
}

定义了高级函数后，就可以调用该函数并检索块了！创建 $Params 变量并将该 splatted 变量传递到 Get-NotionBlock 函数中。这里，仅显示第一个对象。

$Params = @{
    "APIKey"     = 'secret_fS2A21NwTL4L6XWFTTdgmF3xboWiYXExKZ8Pw15oRMw'
    "APIVersion" = '2022-06-28'
    "APIURI"     = 'https://api.notion.com/v1'
    "GUID"       = 'a2b3646de9414df4874d56153139b618'
}

Get-NotionBlock @Params | Select-Object -First 1

如果页面超过 100 块怎么办？当发生这种情况时，该函数会递归运行。通过传入-Verbose参数，您可以看到start_cursor如何变化。为了保持结果简洁，请传递到 Measure-Object cmdlet 以显示返回的超过 158 结果。您可以通过详细输出看出 start_cursor 是在第二次调用中定义的，并且存在更多结果。

奖金！通过 PSDefaultParameterValues 减少传递的参数

您可能已经注意到，在 $Params 块中，您正在传递 API 密钥、API 版本和 API URI。由于这三个值很少改变，因此不必每次都这样做会很方便。 PowerShell 有一种机制可以让这变得更容易。

使用 $PSDefaultParameterValues 变量，您可以定义放置在配置文件中的默认参数值。每次调用函数时，如果运行时没有定义其他值，则会给出这些值。

$PSDefaultParameterValues = @{
    "Get-NotionBlock:APIKey"     = 'secret_fS2A21NwTL4L6XWFTTdgmF3xboWiYXExKZ8Pw15oRMw'
    "Get-NotionBlock:APIVersion" = '2022-06-28'
    "Get-NotionBlock:APIURI"     = 'https://api.notion.com/v1'
}

进行与之前相同的调用，但只需传递 GUID 就意味着您可以更轻松地使用该函数！

包起来

这只是您的 Notion PowerShell 之旅的开始！本文展示了单个 REST API 调用，但为未来的更多可能性奠定了基础。将 Notion 集成到您的 PowerShell 脚本中，并利用这两种技术的灵活性和强大功能。

本文中适用的相同原则也适用于实现所有其他方法，这将在以后的文章中展示！