Skip to content

RESTClass.md

Latest commit

 

History

History
201 lines (158 loc) · 8.68 KB

RESTClass.md

File metadata and controls

201 lines (158 loc) · 8.68 KB
Raw

About the presentation
  • This presentation is about REST and how to use it with Azure
  • It is not a deep dive, but an introduction
  • Let me know if you want a deeper dive with more interactive practice, and I'll develop it

What is REST
  • REST - REpresentational State Transfer
  • Used to send queries and commmands to Azure
  • Used in the background by PowerShell modules and Python libraries
  • not a protocol or a standard, it is an architectural style
  • Stateless - each request is independent and contains all information needed. It does not depend on previously submitted info.

Why is it useful
  • Consistent performance, even if PS modules or Python libraries get updated and change schemas
  • Supports capabilities not yet available in PS modules or Python libraries
  • Works consistently across clouds
  • Useful for understanding how the portal is working and to help in troubleshooting

Structure of a REST call

Pay close attention to the documentation, it often has all the details you need. Finding the right api version through guessing.

If you follow the documentation and get an error, the errors often provide useful information.

Example documentation: https://learn.microsoft.com/en-us/rest/api/authorization/role-definitions/list?view=rest-authorization-2022-04-01&tabs=HTTP

Testing with Insomnia / PostMan

I'll cover insomnia today, but PostMan is also a good tool. Let's just do one to see what it looks like.

  • Getting a bearer token

  • Example0:

    $token = (Get-AzAccessToken -ResourceUrl https://management.azure.com).Token; $token | Set-Clipboard
URI: https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01

  • JSON Path queries

    • Filter the output of the previous command to only show role names
      • $.value[*].properties.roleName
    • Filter the output of the previous command to only show role names that start with "C"
      • $.value[?(@.properties.roleName && @.properties.roleName.match(/^C/))].properties.roleName

  • Example1:

    $graphToken = (Get-AzAccessToken -ResourceUrl 'https://graph.microsoft.us').token; $graphToken | Set-Clipboard
$uri = "https://graph.microsoft.us/v1.0/users"
$uri = "https://graph.microsoft.us/v1.0/users?$select=displayName"
$uri = "https://graph.microsoft.us/v1.0/users?$filter=startswith(displayName,'t')"
https://graph.microsoft.us/v1.0/users?$filter=startswith(displayName,'t')&$select=displayName

  • pagination

    • If you have a large number of results, you may need to paginate through them.
    • Use ?$top=2 as an example
    • Depending on the API are a few different ways to do it. I'll cover this in detail in the longer class if there is sufficient interest.

  • expand, filter, select, orderby

  • https://insomnia.rest

  • https://www.postman.com/

Investigating the portal

 - Using F12 - https://developer.microsoft.com/en-us/graph/graph-explorer - Show parameters, headers, body

Writing in PowerShell

Getting a token - additional info

 - If you don't want to have any dependencies on PowerShell cmdlets then an easy way to get REST endpoints is to just load variables at the beginning of your code 
        Set-Variable -Name managementUrl -Value 'https://management.azure.com' -Option Constant
        Set-Variable -Name StorageTokenResourceUrl -Value 'https://storage.azure.com' -Option Constant
        Set-Variable -Name LoginUrl -Value "https://login.microsoftonline.com" -Option Constant
        Set-Variable -Name GraphResourceUrl -Value "https://graph.microsoft.com" -Option Constant
        Set-Variable -Name StorageResourceUrl -Value "https://storage.azure.com" -Option Constant
        Set-Variable -Name PrivGroupUrl -Value "https://api.azrbac.mspim.azure.com" -Option Constant
        Set-Variable -Name LogAnalyticsUrl -Value "https://api.loganalytics.io" -Option Constant
        Set-Variable -Name odsEndpoint -Value 'ods.opinsights.azure.com' -Option Constant
        Set-Variable -Name SecurityCenterUrl -Value 'https://api-gcc.securitycenter.microsoft.us' -Option Constant
        Set-Variable -Name KeyVaultUrl -Value 'https://vault.azure.net' -Option Constant
  • If you have az.accounts loaded and have ran connect-azaccount, then you can get find endpoints with
Get-AzEnvironment -Name AzureCloud | fl *

For example:

PS C:\Users\pauharri [155]> (Get-AzEnvironment -Name AzureCloud).ResourceManagerUrl
https://management.azure.com/
PS C:\Users\pauharri [127]>

Cmdlets

 
- Invoke-RestMethod
  - Automatically converts response to PS objects from JSON/XML
- Invoke-WebRequest
  - Also works, but I'd use for HTML, not REST
  • Example0: 
    $token = (Get-AzAccessToken -ResourceUrl https://management.azure.com).Token
$uri = "https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?api-version=2022-04-01"
$response = Invoke-RestMethod -Uri $uri -Method Get -Headers @{Authorization = "Bearer $token"}
$response.value | Select-Object -Property id, roleName, description

Wrapper Functions

 
- What is a wrapper function?
- Why use them?
- Examples.

Writing in Python
  • This will be added later if there is interest.

JSON Path Filters

I used JSON Path Filters when looking at output for https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?\$expand=principal $.value[*].principal[createdDateTime]

  • $.value[*].properties
  • $.value[*].properties.roleName
  • $.value[?(@.properties.roleName && @.properties.roleName.match(/^C/))].properties.roleName

Reference Documentation

Code Help Teams Channels
  • Code Help - This is a new team for code help. I've been holding meetings to answer questions and help with PowerShell and REST for a while. If no one has questions I usually have a small lesson, now I'm opening up to a larger group.
  • PowerShell Community - This is the PowerShell community team. It is a great place to ask questions and get help.
  • Python Community - I don't know Pyton well, but the folks here do and are happy to help.