Este tutorial le enseñará cómo crear una función avanzada para interactuar con el API de nociones. Noción es una potente aplicación web para gestionar el conocimiento en espacios de trabajo flexibles. ¡Lleve su automatización al siguiente nivel con la integración de Notion PowerShell!

Requisitos previos

Para seguir este tutorial, solo necesita una cuenta de Notion y Potencia Shell; aquí, se utiliza PowerShell v7.3.7.

Crear un token de integración de Notion

Una vez que haya iniciado sesión en Notion, abra un navegador en el Página “Mis integraciones”. Aquí creará una nueva integración. La clave secreta resultante se utilizará en cada solicitud, autenticando sus llamadas a la API REST.

1. Una vez en el Mis integraciones página, haga clic en “Crear nueva integración“marcador de posición o”+ Nueva integración” botón.

2. A continuación, complete los detalles en consecuencia. Elegir el Espacio de trabajo asociado y dar un Nombre para identificar la integración. Opcionalmente, cargue un Logo para diferenciar aún más su integración.

3. Haga clic en el icono del ojo para mostrar el secreto de integración. Copie este secreto de integración para usarlo más adelante en el script de PowserShell.

4. Navegue hasta el Capacidades sección y realice los cambios necesarios; aquí se utilizan los valores predeterminados.

Interactuar con la API de Notion en PowerShell

Con la integración creada y la clave secreta en la mano, navegue hasta la página indicada con la que interactuará. Puede otorgar acceso de integración al nivel superior, o raíz, de una serie de páginas. Cuando se le concede acceso a la raíz de una serie de páginas, la integración también podrá acceder a todas las páginas secundarias.

En este ejemplo, se creó una página de prueba de PowerShell. Puede agregar el acceso a integraciones a través del menú Conexiones haciendo clic en los tres puntos en la esquina superior derecha para acceder a opciones de menú adicionales. Resalte “Agregar conexiones” y elija la integración recién creada llamada “PowerShell”.

Se mostrará una confirmación y, como se indicó, le preguntará si también otorga acceso de integración a todas las páginas secundarias.

Recuperar los bloques de páginas

Todo en Notion se basa en la idea de bloques. Un párrafo se considera un bloque, incluso si está vacío. Dado que esta página no tiene contenido, puede solicitar el contenido y se devolverá el bloque de párrafo vacío predeterminado.

Necesitará varios datos para crear una llamada de API REST a Notion.

• Clave API – La integración creada previamente y la clave API guardada.
• URI de API – El URL de la API REST.
• Versión API – Los cambios importantes pueden ocurrir, y ocurren, de vez en cuando en la API REST. Debe proporcionar la versión de API con la que está operando. El versión actual es 2022-06-28 en el momento de la creación de este artículo.
• Tamaño de página – Tu solo puedes solicitar tantos bloques en una única llamada a la API REST, y el máximo para la llamada de bloques secundarios es 100.
• GUID (Identificador único global) – Cada página de Notion se identifica por su GUID, el valor agregado después del texto descriptivo. Puede copiar y pegar ese valor desde la URL. Por ejemplo, la página es PowerShell-Testing-a2b3646de9414df4874d56153139b618pero el GUID es a2b3646de9414df4874d56153139b618.

💡 Aunque se muestra la clave secreta, desde entonces se eliminó y ya no es válida.

Con todas esas piezas en la mano, es hora de crear su llamada a la API REST. Como la mayoría de las llamadas a la API REST en PowerShell, llamará al Invoke-RestMethod cmdlet. Los parámetros se presentan utilizando símbolos de parámetros para facilitar la lectura y los resultados de la solicitud se almacenan en el $Result variable. Para ver los resultados, el results La propiedad se solicita al final.

$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

Como puede ver, se devolvió un solo bloque con información detallada. El contenido real, aunque en blanco, está dentro del paragraph propiedad y la rich_text propiedad. En este momento, no hay nada contenido dentro.

Si el texto “¡Hola de Notion!” se ingresa en la página de prueba y el código se vuelve a ejecutar, luego el resultado devuelto rich_text el valor reflejará eso.

Crear una función avanzada de PowerShell

Con lo básico en mano, ¿cuáles son los próximos pasos? Para crear una función reutilizable más sólida, puede aprovechar los principios de la función avanzada de PowerShell. Las mejoras son menos código para ejecutar en la línea de comandos, uso de scripts más sencillo y más validación. Además, con el page_size limite de 100una página que necesitará una llamada recursiva para recuperar todos los resultados, lo que esta función avanzada puede hacer.

Con la intención en mente, ¿cómo funciona el código? Para cualquier función avanzada, debe incluir el [CmdletBinding()] debajo de la declaración de función. Esto indica a PowerShell que puede utilizar las funciones avanzadas.

A continuación, el Param Se declara el bloque de código. Para dos parámetros, $APIURIy $GUIDla validación avanzada se realiza a través del ValidateScript decorador. Utilizando el [System.URI]::IsWellFormedUriString método, esto valida que el valor pasado es un URI preciso. El [GUID]::Parse método en el [GUID] tipo acelerador prueba si el valor pasado es un GUID verdadero.

En el bloque Inicio, en lugar de redefinir los parámetros pasados ​​a Invoke-RestMethod en cada iteración, se definen una vez al inicio del proceso. Las partes más engañosas están en el Process bloquear. El start_cursor El parámetro de Notion define dónde comienza el inicio de la recopilación de resultados. Si se definen, los valores anteriores se omitirán y los siguientes 100 Los bloques se contarán a partir de ahí.

En esta función, eso solo se define en una llamada recursiva. Por ejemplo, Notion devolverá un valor verdadero o falso. $Results.has_more valor si es más de 100 existen bloques. Si esto es cierto, llame al mismo. Get-NotionBlock función, pase los mismos parámetros a través del $PSBoundParameters variable especialy dale el $Result.next_cursor valor a la -StartCursor parámetro. Esto continuará haciéndolo hasta has_more Es falso.

De la misma manera, así es como el has_children La propiedad funciona, ya que es posible que también sea necesario recuperar los bloques secundarios. La función se llamará a sí misma para recuperarlos antes de continuar.

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"
        }
    }
}

Con la función avanzada definida, ¡es hora de llamar a la función y recuperar los bloques! Crea el $Params variable y pasar esa variable salpicada al Get-NotionBlock función. Aquí sólo se muestra el primer objeto.

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

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

¿Qué pasa si la página ha terminado? 100 bloques? Cuando eso sucede, la función se ejecuta de forma recursiva. Al pasar en el -Verbose parámetro, puede ver cómo el start_cursor cambios. Para que los resultados sean concisos, pase al Measure-Object cmdlet para mostrar el final 158 resultados devueltos. Por el resultado detallado se puede decir que el start_cursor se define en la segunda convocatoria y que existan más resultados.

¡Prima! Reducir los parámetros pasados ​​a través de PSDefaultParameterValues

Quizás hayas notado que en el $Params bloque, está pasando la clave API, la versión API y el URI de API. Como estos tres valores rara vez cambian, sería conveniente no tener que hacerlo cada vez. PowerShell tiene un mecanismo para facilitar esto.

Con el $PSDefaultParameterValues variable, puede definir valores de parámetros predeterminados una vez colocados en su perfil. Cada vez que se llama a una función, se proporcionarán estos valores si no se define ningún otro valor en tiempo de ejecución.

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

Haciendo la misma llamada que antes, pero simplemente pasando el GUID ¡Esto significa que puedes usar la función aún más fácilmente!

Terminando

¡Esto es solo el comienzo de su viaje con Notion PowerShell! Este artículo muestra una única llamada a la API REST, pero sienta las bases para más posibilidades en el futuro. Integre Notion en sus scripts de PowerShell y aproveche la flexibilidad y el poder de ambas tecnologías.

Los mismos principios que se aplican en este artículo se aplican a la implementación de todos los demás métodos, que se mostrarán en artículos futuros.