Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Using REST APIs via PowerShell

Guy Leech
September 29, 2022

Using REST APIs via PowerShell

Whilst many PowerShell modules and SDKs are an alternative to calling REST APIs, calling them from PowerShell gives you platform independence, increased speed & no pre-requisites which can be a barrier to adoption. This session shows how to use multiple vendor's REST APIs including Azure & one you know how to call one vendor's API, it's easy to use another's.

This is the slide deck that accompanied my live session at PSConf EU Minicon 2022, a recording of which is available here

https://www.youtube.com/watch?v=eZZaSPa7KNY

Guy Leech

September 29, 2022
Tweet

More Decks by Guy Leech

Other Decks in Technology

Transcript

  1. Using REST APIs via PowerShell
    Guy Leech

    View full-size slide

  2. @guyrleech
    Many thanks to our sponsors:

    View full-size slide

  3. @guyrleech
    Guy Leech
    ▪ Guy is a freelance consultant, speaker and developer, a
    passionate PowerShell scripter, a current Microsoft MVP
    (Cloud and Datacenter Management), Citrix CTP, VMware
    vExpert Parallels VIPP and a veteran of 25+ years in the
    Citrix, Microsoft and VMware End User Computing (EUC)
    space & was a Unix C/C++ developer prior to that. He
    specializes in troubleshooting and automation for both end
    customers and software vendors.
    ▪ Guy was the inventor and initially the sole developer of the
    security product that went on to become AppSense
    Application Manager and now Ivanti Application Control.

    View full-size slide

  4. @guyrleech
    Why use REST ?
    •No pre-requisites other than a language/tools that can drive REST,
    eg PowerShell
    •Code is more portable
    •REST is REST*
    • Learn once, use for multiple vendors/clouds/products
    •My personal experience/perception is that it is faster than
    PowerShell Az cmdlets
    •Why not 😊
    * mostly/kinda/sorta

    View full-size slide

  5. @guyrleech
    Azure REST API
    •Automate deployment, changes, monitoring/alerting, etc
    • If you can do it in the Azure portal, you can do it via REST (and more)
    •REST API usage workflow
    • Authenticate
    • App Registration (one time although will have an expiry date)
    • Different app registrations for different activities for isolation ?
    • Generate bearer token (OAuth 2.0)
    • Pass bearer token in subsequent REST headers
    • Do stuff
    • Get/Set/New/Remove/etc
    • Add required/latest api_version for the provider to the URL
    • Cater for token expiry (default 1 hour) – tells you in the auth response
    • Cater for multiple results “pages”

    View full-size slide

  6. @guyrleech
    Credentials
    •Enter manually when prompted in browser window – not good for lights-
    out automation at 03:15
    • Which you cannot do with REST anyway – an advantage of the Az.* PowerShell modules
    •Service Principal
    • Create an App Registration
    • Make a note of the Application (client) id (a GUID)
    • Create a Client Secret in that app registration & record the secret (password) securely (but not the
    Secret ID)
    • Add to the Access control (IAM) of the required objects, e.g. resource group, with the minimum role
    • e.g. “Reader” only if no requirement to create/change anything inn that object
    •Q. What happens when the person who set up your automation leaves?

    View full-size slide

  7. @guyrleech
    Result Paging
    •Typically occurs when there are >100 items to return (documentation says
    1000)
    •There will be a “nextLink” property present in the response
    •Call the nextLink URL with the same headers/body
    • Optionally check not the same as previous nextLink (defensive programming)
    •All results have been returned when “nextLink” property not present
    •Do not use += for simple arrays as makes a new copy of existing array
    • Use System.Collections.Generic.List[object] and its Add() method
    • Or output results to pipeline and assign to an array variable or return from function
    • [array]$allItems = @( do … while )

    View full-size slide

  8. @guyrleech
    Tracking Asynchronous Operations
    •Operation returns status 201 (Created) or 202 (Accepted)
    •Invoke-RestMethod does not return any JSON so use Invoke-
    WebRequest with same parameters
    • Unless using pwsh 7.x which has –ResponseHeadersVariable
    •Get “Azure-AsyncOperation” property from result headers
    •Call GET on this URL, sleeping between calls (see “Retry-After” in
    result headers but have a sensible default)
    •Loop until “status” property not equal to “InProgress” (implement
    a timeout)
    •Take action depending on “status”

    View full-size slide

  9. @guyrleech
    Guy’s Top Tips
    •Where RTFMing lets you down, use Az.* PS modules & run with –Debug
    5>debug.txt to get URLs, headers, body
    •Cater for transient failures (error 500, timeout & similar) – sleep & retry a small
    number of times
    •Avoid hard coding, e.g. URLs – use script parameters with defaults or declare as
    variable at top of script. They can (and do) change occasionally!
    •Always think “what if this fails or what if it returns 0, 1 or more than 1 item – can
    my code cope?”
    •Watch for infinite (tight) loops
    •Use meaningful variable & function names, no aliases, use full named parameters
    & add comments/references
    •Plenty of examples on line but check not accidentally/intentionally
    malicious/destructive/stupid
    • Re-use/improve scripts/modules but give credit to source (e.g. in a comment) & give back to the community

    View full-size slide

  10. @guyrleech
    Q&A
    15 minutes

    View full-size slide