构建 Concept PowerShell 模块：第 3 部分

在前两个 Notion 教程的基础上，您学习了如何创建 Notion 集成令牌以及如何通过 PowerShell 和 Notion API 检索、更新和删除 Notion 块。

更强大的是 Notion 的数据库。关系数据库有助于逻辑地组织数据并提供分析的机会。使用 Notion，将具有附加属性的页面存储在数据库中。在本教程中，了解如何创建页面、数据库和数据库项。基于 Notion PowerShell 模块构建以继续扩展功能。

先决条件

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

概念数据库的力量

尽管您可能认为页面是独立的，但在 Notion 中，它们也是数据库不可或缺的一部分。因此，将页面操作与数据库操作结合起来有助于理解其中的联系。在概念中，数据库可能具有许多不同类型的属性，例如选择、复选框或数字。

创建页面

首先，您需要一个放置数据库的地方。为了演示这一点，请使用 /pages 端点创建一个新页面。生成的 id 将是用作新数据库的 parent_id 的 GUID。

$APIKey     = 'secret_sK5Qir0UAgkLF1iauP5iMsq1vq3YW5S9o5GvF7M8PjK'
$APIURI     = 'https://api.notion.com/v1'
$APIVersion = '2022-06-28'
$GUID       = 'a2b3646d-e941-4df4-874d-56153139b618'

$Params = @{
    "Headers" = @{
        "Authorization"  = "Bearer {0}" -F $APIKey
        "Content-type"   = "application/json"
        "Notion-Version" = "{0}" -F $APIVersion
    }
    "Method"  = 'POST'
    "URI"     = ("{0}/pages" -F $APIURI, [GUID]::new($GUID))
    "Body"    = @{
        "parent" = @{
            "type"    = 'page_id'
            "page_id" = $GUID
        }
        "properties" = @{
            "title" = @(
                @{
                    "text" = @{"content" = "Test" }
                }
            )
        }
        "children" = @()
    } | ConvertTo-JSON -Depth 100
}

$Result = Invoke-RestMethod @Params

创建数据库

对于新创建的页面，您将使用 page_id 父级和 /databases 端点来创建一个具有单个必需 Title 属性的新数据库。有一个必需的 title 属性也为数据库提供了唯一的名称。

$Params = @{
    "Headers" = @{
        "Authorization"  = "Bearer {0}" -F $APIKey
        "Content-type"   = "application/json"
        "Notion-Version" = "{0}" -F $APIVersion
    }
    "Method"  = 'POST'
    "URI"     = ("{0}/databases" -F $APIURI)
    "Body"    = @{
        "parent" = @{
            "type"    = "page_id"
            "page_id" = $Result.id
        }
        "title" = @(
            @{
                "type" = "text"
                "text" = @{
                  "content" = "Test"
                  "link" = $null
                }
            }
        )
        "properties" = @{
            "Name" = @{
                "type" = "title"
                "title" = @{}
            }
						"Checkbox" = @{
                "type" = "checkbox"
                "checkbox" = @{}
            }
            "Number" = @{
                "type" = "number"
                "number" = @{
                  "format" = "number_with_commas"
                }
            }
        }
    } | ConvertTo-Json -Depth 100
}

$Result = Invoke-RestMethod @Params

在数据库中创建页面

最后，要在数据库中存储数据，您必须创建一个新项目：完整的概念页面。由于页面项存在于数据库中，因此它具有任何附加属性的额外好处。在上面的示例中，您创建了一个复选框和数字属性。

$Params = @{
    "Headers" = @{
        "Authorization"  = "Bearer {0}" -F $APIKey
        "Content-type"   = "application/json"
        "Notion-Version" = "{0}" -F $APIVersion
    }
    "Method"  = 'POST'
    "URI"     = ("{0}/pages" -F $APIURI)
    "Body"    = @{
        "parent" = @{
            "type"        = "database_id"
            "database_id" = $Result.id
        }
        "properties" = @{
            "Name" = @{
                "title" = @(
                    @{
                        "text" = @{"content" = "This is a Test Task"}
                    }
                )
             }
             "Checkbox" = @{
                "checkbox" = $True
             }
             "Number" = @{
                "number" = 1000
             }
        }
    } | ConvertTo-Json -Depth 100
}

$Result = Invoke-RestMethod @Params

添加到模块

为了完善该模块，将创建三个新函数。这些功能将是：

New-NotionPage

New-NotionDatabase

您可能想知道为什么没有 New-NotionDatabase。从技术上讲，您为数据库和页面调用相同的端点 /pages，因此您可以扩展 New-NotionPage 函数以涵盖这两个用例。

该函数引入的是参数集的概念。参数集提供了一种将参数分成逻辑分组并且只允许那些属于在一起的参数的方法。下面定义的是 CmdletBinding 声明中的 DefaultParameterSetName。这给出了该函数的默认值。

有必要定义每个参数所属的所有参数集。如果一个参数必须同时存在于两个参数集中，则必须使用多个声明。

新概念页面

Function New-NotionPage {
    [CmdletBinding(SupportsShouldProcess = $True, DefaultParameterSetName = 'Page')]
  
    Param(
        [String]$APIKey,
        [String]$APIVersion,
        [ValidateScript( { [System.URI]::IsWellFormedUriString( $_ ,[System.UriKind]::Absolute ) } )][String]$APIURI,

        [Parameter(ValueFromPipelineByPropertyName = $True)]
        [Alias("ID")]
        [ValidateScript( { Try { If ( [GUID]::Parse( $_ ) ) { $True } } Catch { $False } } )][String]$GUID,

        [Parameter(Mandatory, ParameterSetName = 'Page')]
        $Title,

        $Content,

        [Parameter(ParameterSetName = 'Database')]
        $Properties,

        [Parameter(ParameterSetName = 'Database')]
        [Switch]$Database
    )
  
    Process {
        $Body = @{
            "parent"     = $Null
            "properties" = $Null
        }

        If ($Database) {
            $Body.properties = $Properties
            $Body.parent = @{
                "type"    = 'database_id'
                "database_id" = [GUID]::New($GUID)
            }
        } Else {
            $Body.parent = @{
                "type"    = 'page_id'
                "page_id" = [GUID]::New($GUID)
            }
            $Body.properties = @{
                "title" = @(
                    @{
                        "text" = @{ "content" = $Title }
                    }
                )
            }          
        }

        If ($Content) {
            $Body.Add("children", $content)
        }

        Write-Verbose ($Body | Out-String)

        $Params = @{
            "Headers" = @{
                "Authorization"  = "Bearer {0}" -F $APIKey
                "Content-type"   = "application/json"
                "Notion-Version" = "{0}" -F $APIVersion
            }
            "Method" = 'POST'
            "URI"    = ("{0}/pages" -F $APIURI)
            "Body"   = $Body | ConvertTo-JSON -Depth 100
        }

        Write-Verbose "[Process] Params: $($Params | Out-String)"

        If ($PSCmdlet.ShouldProcess($GUID,"Adding Page")) {
            Try {
                $Result = Invoke-RestMethod @Params -ErrorAction 'Stop'
            } Catch {
                $Message = ($Error[0].ErrorDetails.Message | ConvertFrom-JSON).message

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

            If ($Result) {
                $Result
            }
        }
    }
}

新概念数据库

Function New-NotionDatabase {
    [CmdletBinding(SupportsShouldProcess = $True)]
  
    Param(
      [String]$APIKey,
      [String]$APIVersion,
      [ValidateScript( { [System.URI]::IsWellFormedUriString( $_ ,[System.UriKind]::Absolute ) } )][String]$APIURI,
  
      [Parameter(ValueFromPipelineByPropertyName = $True)]
      [Alias("ID")]
      [ValidateScript( { Try { If ( [GUID]::Parse( $_ ) ) { $True } } Catch { $False } } )][String]$GUID,

      [Parameter(Mandatory)]
      $Title,
  
      $Properties
    )
  
    Process {
        $Params = @{
            "Headers" = @{
                "Authorization"  = "Bearer {0}" -F $APIKey
                "Content-type"   = "application/json"
                "Notion-Version" = "{0}" -F $APIVersion
            }
            "Method" = 'POST'
            "URI"    = ("{0}/databases" -F $APIURI)
            "Body"   = @{
                "parent" = @{
                    "type"    = 'page_id'
                    "page_id" = [GUID]::New($GUID)
                }
                "title" = @(
                    @{
                        "type" = "text"
                        "text" = @{
                          "content" = $Title
                          "link" = $Null
                        }
                    }
                )
                "properties" = $Properties
            } | ConvertTo-JSON -Depth 100
        }

        Write-Verbose "[Process] Params: $($Params | Out-String)"

        If ($PSCmdlet.ShouldProcess($GUID,"Adding Database")) {
            Try {
                $Result = Invoke-RestMethod @Params -ErrorAction 'Stop'
            } Catch {
                $Message = ($Error[0].ErrorDetails.Message | ConvertFrom-JSON).message

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

            If ($Result) {
                $Result
            }
        }
    }
}

一起运行时，您可以看到结果与运行单独的 API 调用相同，但命名法更加用户友好。通过传入先前调用的结果对象，您可以简化子页面和对象的创建。

$Parent = 'a2b3646de9414df4874d56153139b618'

$Result = New-NotionPage -GUID $Parent -Title "Database Page"

$Database = New-NotionDatabase -GUID $Result.id -Title "Test Database" -Properties @{
    "Name" = @{
        "type" = "title"
        "title" = @{}
    }
    "Checkbox" = @{
        "type" = "checkbox"
        "checkbox" = @{}
    }
    "Number" = @{
        "type" = "number"
        "number" = @{
          "format" = "number_with_commas"
        }
    }
}

$Item = New-NotionPage -Database -GUID $Database.id -Properties @{
    "Name" = @{
        "title" = @(
            @{
                "text" = @{"content" = "This is a Test Task"}
            }
        )
     }
     "Checkbox" = @{
        "checkbox" = $True
     }
     "Number" = @{
        "number" = 1000
     }
}

下一步

下一步是向模块添加一些支持功能，以创建更强大的可用块类型类型和额外的可用性。接下来的几篇文章将会对这个功能进行总结，完成一个可用的、功能齐全的模块的创建！