Deep Dive into Windows 365 APIs

As I wrote about recently, Windows 365 has a deep set of capabilities. Anytime you manage a platform, you should be thinking about how can I extend/push the limit of the platform. The answer to that almost every time will be the API. Today, we will take a look at the exposed Windows APIs and how we can use them to make Windows 365 even easier to manage and utilize. We will take a look at the framework of leveraging the API via PowerShell and then check out the various APIs that are available today.

How to Use the Windows 365 API in PowerShell

Leveraging the API is pretty straight forward. First, we will setup the App Integration, authenticate to it, and then make calls against it inside of PowerShell. Let’s get started!

Setting up the App Integration for the Windows 365 API

First, we will create a new app registration like this below:

Next, make note of the “client ID” for your script and go to “API Permissions”

Now, click “Add a Permission” > Microsoft Graph”

Select “Delegated permissions” add the Cloud PC permissions and then repeat for “Application permissions”

Once done, you need to “Grant Admin Consent”

You can see the happy checkmarks once done!

The last thing you need to do is create your client secret. Go to “Certificates & secrets” and “New client secret” to generate the secret we need for our API scripts.

Copy your secret when done, and you’re ready to move onto scripting!

Walking through the API Script Template

The script has two parts, the authentication and the actual API commands you are running to work your magic.

First, let’s check out the authentication, which is pretty simple. You put your stuff from your App Registration in there and that will get the token that authenticates you to the Graph API.

##Create your Auth Body##
$Body = @{
      "grant_type" = "client_credentials";
      "scope" = "https://graph.microsoft.com/.default";
      "client_id"="dabc7303-45ab-4a7d-889c-517c94209eae";
      "client_secret" ="MlU8Q~6P.-Cgj22D2rOzz";
    }

##Get your Bearer Token##
$token = Invoke-RestMethod -Uri "https://login.microsoftonline.com/d2e17a63-6944-4f67-b776-53640b6bd0f7/oauth2/v2.0/token" -Method POST -Headers $headers
$accessToken = $token.access_token

The second

##Craft the Headers with the Bearer Token##
$Headers =@{
        "Authorization"="Bearer $accessToken";
    }

##Query your Provisioning Policies##
$ProvisioningPolicyList = Invoke-RestMethod -Uri https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/provisioningPolicies -Headers $Headers
$ProvisioningPolicyList.value

You can see the results are nice and readable:

The Available Windows 365 APIs

Microsoft has a nice little article on the various APIs here. Basically, we have 7 categories:

Cloud PC Provisioning Policies
Cloud PC Device Management
Cloud PC Images
Cloud PC On-Premises Connections
Cloud PC Audit Events
Cloud PC User Settings
Cloud PC Alert Monitoring

Now, let’s discuss some of these items and some potential real-world examples in detail. You can obviously also use the PowerShell module, but we’re focusing on straight API today.

Cloud PC Provisioning Policies API

Provisioning Policies are basically the automated process that creates a cloud PC, sets it up for the user, completes provisioning tasks, etc. We can use these API sets to list policies, read specific policies, create, delete, assign, and update policies. Let’s walk through using some code to create assignments against the policy.

The main challenge is that you need to specify all of the assignments when you assign the policy or it blows out the rest of them. First, you need to get the policy ID with this command:

$ProvisioningPolicy = Invoke-RestMethod -Uri https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/provisioningPolicies -Headers $Headers
$ProvisioningPolicyID = $ProvisioningPolicy.value.id

Once that gives you the ID, you can use that to set your policy. One of the issues currently is that you cannot get your assignments of a provisioning policy via API.

I didn’t get too crazy here, but you can see below how we define the body in JSON and use that to set the groups needed for the provisioning policy via API:

$json = @"
{
  "@odata.type": "#microsoft.graph.cloudPcProvisioningPolicyAssignment",
  "assignments": [
    {
      "id": "policyid_groupid1",
      "target":{
        "@odata.type": "microsoft.graph.cloudPcManagementGroupAssignmentTarget",
        "groupId":"groupid1"
        }
    },
        {
      "id": "policyid_groupid2",
      "target":{
        "@odata.type": "microsoft.graph.cloudPcManagementGroupAssignmentTarget",
        "groupId":"groupid2"
        }
        }
  ]
}
"@
Invoke-RestMethod -Uri https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/provisioningPolicies/$ProvisioningPolicyID/assign -Headers $Headers -Method Post -Body $json

Cloud PC Device Management API

The Device Management API is very useful. You can do a ton of different things like:

Reboot a Cloud PC
Reprovision a Cloud PC
Restore to previous snapshots
End grace period
Rename the PC and more!

Let’s check out a fun example where we will print the list of the Cloud PCs so we can reprovision a Cloud PC.

First, let’s grab the devices and print the info we care about

$Devices = Invoke-RestMethod  https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/cloudPCs -Headers $headers
$Devices.value | select id, displayName, userprincipalname

That makes it looks like this:

Now, I extend it a bit more to select an exact Id (I’m not going crazy or anything with this but keeping it simple (obviously I can do it more gracefully but that isn’t the point):

 $ReprovisionID = $Devices.value | Where-Object -FilterScript {$_.userPrincipalName -eq '[email protected]'} | Select id

Now, I trigger the command to reprovision that PC:

Invoke-RestMethod  https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/cloudPCs/$ReprovisionID/reprovision

Cloud PC Images API

We won’t cover this one too much right now as I am working mostly with built-in images as Azure has some really strong ones. I will update this when I revisit it.

You can leverage the images API to do the following:

List your custom images
Read a specific custom image
Create a cloud PC image
Delete a cloud PC image
Get source images
Reupload cloud PC device images

Cloud PC User Settings API

The Cloud PC user settings API is another important one and how we will wrap up this article. Some of the settings you can update are:

Modify local admin settings
Modify self service settings
Set restore point settings

You can do your typical stuff with list, get, create, update, delete, and assign user settings objects.

Let’s create a new policy for 12-hour backups as a nice and fun use of the API. Not a big deal at all.

##Set Headers for the Command##
$Headers =@{
        "Authorization" = "Bearer $accessToken";
        "Content-Type" = "application/json";
    } 
##Create the Json Body for the Creation##
$json = @"
{
  "@odata.type": "#microsoft.graph.cloudPcUserSetting",
  "displayName": "6-hour backup", 
  "localAdminEnabled": "true",
  "restorePointSetting": {
    "@odata.type": "microsoft.graph.cloudPcRestorePointSetting",
  "frequencyInHours": "6",
  "userRestoreEnabled": "true"
  },
  "selfServiceEnabled": "true"
}
"@
##Create the User Settings Object##
$userSettings = Invoke-RestMethod  https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/userSettings -Headers $Headers -Method Post -Body $json

##Capture the User Settings ID for the assignment
$userSettingsID = $userSettings.id

Once you finish up, you can assign that policy just like we covered earlier on:

$json = @"
{
  "@odata.type": "#microsoft.graph.cloudPcUserSettingAssignment",
  "assignments": [
    {
      "id": "policyid_groupid1",
      "target":{
        "@odata.type": "microsoft.graph.cloudPcManagementAssignmentTarget",
        "groupId":"groupid1"
        }
    },
        {
      "id": "policyid_groupid2",
      "target":{
        "@odata.type": "microsoft.graph.cloudPcManagementAssignmentTarget",
        "groupId":"groupid2"
        }
        }
  ]
}
"@
Invoke-RestMethod -Uri https://graph.microsoft.com/beta/deviceManagement/virtualEndpoint/userSettings/$userSettingsID/assign
 -Headers $Headers -Method Post -Body $json

Final Thoughts

The Windows 365 API is a really fun venture, but not without its challenges. I’m used to it by now how you need to know all of the assignments when leveraging the API, but it can certainly trip some people up. Most people will wonder why I’m not just using the PowerShell modules, but I just find the API to be really easy to use and provides some great opportunities to do some ITSM orchestration as well.

HEADLINES:

HEADLINES:

Mobile Jon's Blog