https://github.com/sikkepitje/woots-powershell
PowerShell module wrapper for Woots API v2
https://github.com/sikkepitje/woots-powershell
api-wrapper cbt dutch-language education powershell powershell-module school-stuff web woots
Last synced: 5 months ago
JSON representation
PowerShell module wrapper for Woots API v2
- Host: GitHub
- URL: https://github.com/sikkepitje/woots-powershell
- Owner: sikkepitje
- Created: 2022-07-04T13:30:39.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-09-13T07:26:15.000Z (almost 2 years ago)
- Last Synced: 2025-06-29T18:52:17.424Z (about 1 year ago)
- Topics: api-wrapper, cbt, dutch-language, education, powershell, powershell-module, school-stuff, web, woots
- Language: PowerShell
- Homepage:
- Size: 58.6 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
Awesome Lists containing this project
README
= Woots PowerShell
== Abstract
Op deze Github vind je een PowerShell module voor het interfacing met Woots Web API v2. Dit is gebaseerd op de https://app.woots.nl/api/docs/index.html#/[Woots API documentatie].
Op dit moment zijn 185 API aanroepen als functie geimplementeerd. Daarvan zijn 2 nog niet geimplementeerd.
== Vereisten
Woots PowerShell module vereist PowerShell 5, PowerShell 7 of hoger.
== Installatie
De module bestaat uit drie bestanden: ``Woots.psm1``, ``Woots.psd1`` en ``Woots-generatedcode.ps1``.
. Bepaal de PowerShell modulemap waar je de Woots module wilt toevoegen.
. Maak hierin een submap ``Woots``.
. Download de bestanden ``Woots.psm1``, ``Woots.psd1`` en ``Woots-generatedcode.ps1`` en plaats deze in een PowerShell modulemap.
[NOTE]
====
Een modulemap voor Windows PowerShell tot en met versie 5.1 is bijvoorbeeld ``C:\Users\username\Documents\WindowsPowerShell\Modules``. Raadpleeg de environment variabele ``$ENV:PSModulePath`` om te zien waar de modulemappen op jouw computer staan.
====
== Gebruik
Je kunt de module in je scripts gebruiken door de module te importeren als volgt.
[source,PowerShell]
----
Import-Module Woots
----
Initializeer Woots door een aanroep naar ``Initialize-Woots``. Deze functie verwacht 3 parameters:
* ``$Hostname`` :
Dit is de hostname deel van de Woots API endpoint URL. In geval van https://app.woots.nl/api/v2,
dan is dit het deel "app.woots.nl".
* ``$School_id`` :
Dit is een unieke nummer voor de schoolomgeving in Woots. De school_id is zichtbaar in de Wootsportal
onder Mijn account > API-token.
* ``$Token`` :
Dit is een hexadecimale string van 30 tekens waarmee toegang tot de Woots API wordt geauthoriseerd.
Je kunt deze aanmaken in de Wootsportal onder Mijn account > API-token.
== Documentatie
Werp een blik op de functiedefinities in ``Woots-generatedCode.ps1`` om te zien welke functies er allemaal gedefinieerd zijn.
=== Functieparameters
Alle functies slechts één of meer van de volgende parameters.
* ``$Id`` : het numeriek ID van de resource waarop de bewerking betrekking heeft (alle functies van de categorie Get-Resource, Get-ResourceItem, Set-Resource, Add-ResourceItem, Remove-Resource).
* ``$Parameter`` : een hastable met de in te stellen attributen van een resource (alle functies van de categorie Add-Resource, Add-ResourceItem, Set-Resource, Set-ResourceItem), of een hashtable met naam-waarde-paren die het filter definieren voor een zoekactie (alle functies van de categorie Search-Resource).
* ``$MaxItems`` : een getal , dat indien groter dan 0, het hoogste aantal items aangeeft, dat moeten worden opgehaald. Bij weglating van deze parameter of bij een negatieve waarde, wordt het maximum aantal beschikbare items geretourneerd (alle functies van de categorie Search-Resource, Get-AllResources).
Alle parameters zijn PowerShell objecten, behalve waar het gaat om booleaanse waarden; in dat geval volstaat de string ``"false"`` of ``"true"``.
Voorbeeld:
----
$filter = @{
name = "Aardrijkskunde"
trashed = "false"
}
$result = Search-WootsCourse -Parameter $filter
----
=== Functieretourwaarden
Alle functies retourneren wat er wordt opgehaald via de API aanvraag.
== Extra's
Een deel van de code in de module is gegenereerd door een codegenerator.
* ``WootsModuleCodeGenerator.ps1`` : dit script genereert de code in ``Woots-generatedcode.ps1``.
* ``Woots-api-calls.csv`` : dit bestand wordt ingelezen door ``WootsModuleCodeGenerator.ps1``.
== Changes
* 20230802 : added "charset=utf-8" to contenttype of Invoke-WebRequest to be able to send special chars in names and such.
=== WootsModuleCodeGenerator.ps1
* 20230815 Extract api calls automatically from https://stage.woots.nl/api/docs/v2/swagger.yaml
* 20230815 Added generation date and openapi version umber in generated code
* 20230815 added API call for logs
* 20230815 output code sorted and grouped by category