Name: Tremplin Numérique
Price range: $$$

apprentissage-d39une-nouvelle-api-rest-avec-powershell-cloudsavvy-it-4405151

L'utilisation d'API REST pour étendre vos scripts est une fonctionnalité utile à implémenter. Vous pouvez accéder à de nouvelles fonctionnalités et les possibilités de création de nouveaux scripts plus avancés se développent.

Mais l'expérience de nombreux utilisateurs qui commencent à utiliser les API REST dans les scripts est que cela semble assez maladroit et peu naturel. Dans cet article, nous discutons:

Qu'est-ce qu'une API REST
Comment lire la forme de documentation la plus courante
Comment utiliser une API REST avec PowerShell
Quelques trucs et astuces pour en faire une expérience plus facile et meilleure

Sommaire

Qu'est-ce que REST?

REST, ou RESTful API, est une API qui utilise des requêtes HTTP pour récupérer, ajouter, supprimer ou manipuler des données dans différents services.

Ce que nous voulons faire avec les données est généralement décidé par la méthode HTTP que vous utilisez. Voici une liste résumée des méthodes HTTP et de ce qu'elles sont utilisées pour faire dans une API REST:

GET — Lire
POST — Créer
PATCH — Mise à jour / modification partielle
PUT — Mettre à jour / remplacer
SUPPRIMER — Supprimer

Les données renvoyées par une API REST sont généralement renvoyées au format JSON.

Commençons maintenant avec notre premier appel d'API!

Lire les documents

Apprendre à lire et à interpréter la documentation des différentes API REST est essentiel pour les utiliser. Heureusement, si vous savez lire un style de documentation, vous pouvez apprendre rapidement à en lire d'autres.

Nous utilisons petstore.swagger.io dans cet article, car il utilise le framework Swagger populaire qui est assez courant à rencontrer dans le monde réel.

1591732174_252_apprentissage-d39une-nouvelle-api-rest-avec-powershell-cloudsavvy-it-9080491

L'image précédente montre les informations les plus essentielles sur les points de terminaison de l'API REST:

Méthode HTTP: GET / POST / DELETE, etc.
URL relative au point de terminaison de l'API REST (l'URL de base est généralement présentée en haut de la page de documentation)
Une brève description

Entrer dans les détails

La première page de la documentation est excellente et vous pouvez généralement effectuer la plupart des appels qui nécessitent la méthode HTTP GET avec ces informations. Mais les méthodes comme POST et SET nécessitent généralement que vous cliquiez et développiez la ligne pour obtenir plus d'informations.

Si vous cliquez sur l'une des lignes, vous obtenez des informations qui ressemblent à ceci:

1591732174_405_apprentissage-d39une-nouvelle-api-rest-avec-powershell-cloudsavvy-it-9066293

Ici, nous avons présenté le point de terminaison REST qui peut créer un nouvel objet animal. Il spécifie à quoi doit ressembler le JSON fourni dans le corps du POST et quel type de contenu il accepte. Les autres points de terminaison REST spécifient quels sont les différents paramètres, quel type de données il doit être, etc.

Voilà les bases pour lire la documentation. Maintenant que c'est clair, il est temps de commencer à utiliser les API REST avec PowerShell.

OBTENEZ (ting) vos premières données

L’utilisation des API REST avec PowerShell est généralement assez simple et vous utilisez des applets de commande intégrées, donc aucun module supplémentaire n’est nécessaire. Vous allez récupérer des données en utilisant la méthode GET sur / pet / {petId} point final.

Si vous développez le / pet / {petId} point final dans la documentation, vous pouvez voir que {petId} est en fait un paramètre qui prend un entier.

1591732174_799_apprentissage-d39une-nouvelle-api-rest-avec-powershell-cloudsavvy-it-3349846

Cela fait l'URL pour récupérer l'objet animal de compagnie avec l'ID 1: https://petstore.swagger.io/v2/pet/1

La documentation de l'API SWAGGER REST présente généralement l'URL de base en haut de la page.

Maintenant, commençons avec PowerShell. Ouvrez une fenêtre de terminal et entrez:

PS51 > Invoke-RestMethod -Method GET -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"

id        : 1
category  : @{id=0; name=string}
name      : doggie
photoUrls : {string}
tags      : {@{id=0; name=string}}
status    : available

Invoke-RestMethod convertit automatiquement le JSON renvoyé en objet, car le type de contenu «application / json» est renvoyé dans la réponse du serveur.

Error 404 - Not found signifie généralement que l’objet est introuvable, et non que l’URL est mal tapée.

Vous avez maintenant effectué avec succès votre premier appel d'API REST. Mais seule la possibilité d'obtenir des données est assez limitative. Créons donc quelque chose avec la méthode POST.

Création d'un objet avec la méthode POST

La méthode POST est le plus souvent utilisée pour créer, comme la création d'utilisateurs ou d'entrées, etc. Une demande POST envoie un BODY contenant des informations au point de terminaison REST, généralement au format JSON, mais elle peut également être sous forme codée URL.

Vous allez apprendre à créer un objet JSON que vous pouvez POSTER sur le /animal de compagnie point final.

Vous pouvez voir à quoi le JSON est censé ressembler si vous développez POST / animal ligne dans la documentation.

1591732174_560_apprentissage-d39une-nouvelle-api-rest-avec-powershell-cloudsavvy-it-3042175

Commençons par créer une table de hachage que nous pourrons ensuite convertir en objet JSON. Le JSON brut doit être évité dans les scripts PowerShell car il limite ses capacités.

$Body = @{
    id = 19
    category = @{
        id = 45
        name = "Whatever"
    }
    name = "Dawg"
    photoUrls = @(
        "string"
    )
    tags = @(
        @{
            id = 0
            name = "string"
        }
    )
    status = "available"
}

Si vous avez du mal à créer une table de hachage qui se convertit au JSON souhaité, installez le module PsdKit et utilisez la commande: $JsonString | ConvertTo-Psd

Vous avez maintenant une table de hachage que vous pouvez convertir en chaîne JSON et POST en /animal de compagnie point final:

$JsonBody = $Body | ConvertTo-Json
$Uri = "https://petstore.swagger.io/v2/pet"
Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method Post -Body $JsonBody

id        : 19
category  : @{id=45; name=Whatever}
name      : Dawg
photoUrls : {string}
tags      : {@{id=0; name=string}}
status    : available

Lorsque l'objet est créé, vous recevez généralement l'objet créé pour confirmation.

Utiliser DELETE

La méthode DELETE supprime les données, et la façon de le faire est assez similaire à la méthode GET comme illustré ici:

PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"

Sachez simplement que vous ne supprimez rien dont vous pourriez avoir besoin.

Utilisation de PUT

La méthode PUT met à jour les données déjà existantes. Cela se fait de manière similaire à la méthode POST, en soumettant un objet JSON complet ou partiel:

PS51> $Body = (PSCustomObject)@{
    id = 19
    name = "Dawg with a new name"
}

PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = "https://petstore.swagger.io/v2/pet"
PS51> Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method PUT -Body $JsonBody

id name                 photoUrls tags
-- ----                 --------- ----
19 Dawg with a new name {}        {}

Habituellement, l'API REST renvoie un objet JSON avec les données utilisées et / ou mises à jour. Vous pouvez voir que l'objet a été mis à jour en utilisant la méthode GET vers lui:

PS 51> Invoke-RestMethod -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/19"

id        : 19
category  : @{id=45; name=Whatever}
name      : Dawg with a new name
photoUrls : {string}
tags      : {@{id=0; name=string}}
status    : available

Création de fonctions

L'écriture de ces commandes telles qu'elles sont peut devenir assez fastidieuse et n'est pas vraiment évolutive. Si nous appelons un point de terminaison plus d'une fois, créez-lui une fonction. C'est assez simple et seules quelques lignes sont nécessaires:

Function Get-PetstorePet {
    (cmdletbinding())
    param(
        # Id of the pet
        (Parameter(Mandatory,ValueFromPipeline))
        (int)$Id
    )
    Begin{}
    Process{
        $RestMethodParams = @{
            Uri = "https://petstore.swagger.io/v2/pet/$Id"
            ContentType = "application/json"
            Method = "GET"
        }
        Invoke-RestMethod @RestMethodParams
    }
    End{}
}

Après avoir créé votre fonction, vous pouvez l'appeler dans votre script:

PS51> Get-PetstorePet -Id 1

id name    photoUrls             tags
-- ----    ---------             ----
 1 Doggie  {http://picture.url}  {}

Vous pouvez le faire pour la méthode POST ainsi que pour créer un nouvel animal dans l'animalerie:

Function Add-PetstorePet {
    (cmdletbinding())
    param(
        # Id of the pet
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (int)$Id,
        # Name of the pet
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (string)$Name,        
        # Status of the pet (available, sold etc)
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (string)$Status,        
        # Id of the pet category
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (int)$CategoryId,        
        # Name of the pet category
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (string)$CategoryName,        
        # URLs to photos of the pet
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (string())$PhotoUrls,
        # Tags of the pets as hashtable array: @{Id=1;Name="Dog"}
        (Parameter(Mandatory,ValueFromPipelineByPropertyName))
        (Hashtable())$Tags
    )
    Begin{}
    Process{
        $Body = @{
            id = $Id
            category = @{
                id = $CategoryId
                name = $CategoryName
            }
            name = $Name
            photoUrls = $PhotoUrls
            tags = $Tags
            status = $Status
        }
        $BodyJson = $Body | ConvertTo-Json
        $RestMethodParams = @{
            Uri = "https://petstore.swagger.io/v2/pet/"
            ContentType = "application/json"
            Method = "Post"
            Body = $BodyJson
        }
        Invoke-RestMethod @RestMethodParams
    }
    End{}
}

Et appeler cette fonction PowerShell par la suite rend cette tâche assez longue beaucoup plus facile:

PS51> $AddPetStorePetsParams = @{
    Id = 44
    Name = "Birdie"
    Status = "available"
    CategoryId = 50
    CategoryName = "Hawks"
    PhotoUrls = "https://images.contoso.com/hawk.jpg"
    Tags = @(
        @{
            Id=10
            Name="Not eagles"
        }
    )
}
PS51> Add-PetStorePet @AddPetStorePetsParams

id        : 44
category  : @{id=50; name=Hawks}
name      : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags      : {@{id=0}}
status    : available

Il est probable que la plupart des modules que vous utilisez quotidiennement sont constitués de fonctions qui n'utilisent que les API REST en arrière-plan.

Sommaire

Apprendre à utiliser les API REST consiste principalement à apprendre à lire la documentation. Nous avons utilisé la documentation basée sur SWAGGER dans ce post, car elle représente à quoi peuvent ressembler d'autres styles de documentation.

De plus, la conversion de vos appels d'API en fonction peut vous faire gagner beaucoup de temps, faciliter votre travail et nettoyer vos scripts.