Send device command (deprecated)

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Caution

This API is deprecated and stopped returning data on September 30, 2020.

This API enables Project Rome capabilities to command a device associated with a Microsoft account. After doing a GET call on me/devices, pass in the ID of the device to issue a command to your device. Two types of commands are supported: LaunchURI and AppServices. If you're using LaunchURI, specify the type and payload parameters. For an AppService call, specify the type, payload, packageFamilyName, and appServiceName parameters.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	❌	❌	❌

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	Not supported.	Not supported.
Delegated (personal Microsoft account)	Device.Command	Not available.
Application	Not supported.	Not supported.

HTTP request

POST me/devices/{id}/commands

Request headers

Header	Value
Authorization	Bearer {token}. Required. Learn more about authentication and authorization.
Accept	application/json

Request body

In the request body, supply a JSON representation of the command properties.

{
  "type": "appService",
  "payload": "payload-JSON",
  "packageFamilyName": "packageFamilyName",
  "appServiceName": "appServiceName",
  "postbackURI": "postbackURI"
}

Response

HTTP/1.1 201 OK

{
  "id": "0",
  "status": "requesting",
  "type": "appService",
  "appServiceName": "appServiceName",
  "packageFamilyName": "packageFamilyName",
  "error": "null",
  "responsePayload": "null",
  "payload": "payload-JSON",
  "permissionTicket": "null",
  "postBackUri": "postbackURI"
}

Command properties

Name	Type	Description
payload	microsoft.graph.json	Payload to send to an app service or to launch a URI on a device.
responsePayload	microsoft.graph.json	Payload returned from target device.
postBackURI	String	Post back URI to send subsequent notifications of updates.
packageFamilyName	String	Windows Package Family Name of application.
appServiceName	String	Name of app service defined by the target application. Required if launching an app service.
type	String	LaunchURI or AppService.
id	String	The ID of a command that has been sent to the device.
actionStatus	String	The status of a command.
error	String	Any errors associated with the request from the target application.

Examples

Example 1: Launch URI

The following is an example of a LaunchURI request; it will launch a URI or an application on the target device. To launch a URI or an app, issue a POST using the ID of the device (obtained from doing a GET call on me/devices). Set the Type parameters to LaunchURI and provide a URI value such as https://bing.com.

Request

POST me/devices/{id}/commands
Authorization: Bearer Eaeou....
Content-Type: application/json; charset=utf-8

{ "type" : "LaunchUri", "payload" : {"uri":"https://bing.com"}}

Response

HTTP/1.1 201 OK

{
  "id": "0158355AD4D680CC4E2994CC009EFFD7337D1B...",
  "status": "requesting",
  "type": null,
  "appServiceName": null,
  "packageFamilyName": null,
  "error": null,
  "permissionTicket": null,
  "postBackUri": null,
  "payload": {
    "uri": "https://bing.com"
  }
}

Example 2: App service

The following example shows how to query an app service on a device. To use an app service, you must do a POST call using the ID of the device (obtained from doing a GET call on me/devices). To use the following example, you must install the Rome app on your target device.

Several additional properties must be set in the call. Type must be set to AppService, AppServiceName must be set to the name of the app service defined in the application, PackageFamilyName must be set to the package family name defined in the app manifest, and Payload holds the keys and values for the service you are calling within the target application.

Request

POST me/devices/{id}/commands
Authorization: Bearer Eaeou....
Content-Type: application/json; charset=utf-8

{
  "type" : "AppService",
  "appServiceName" : "com.microsoft.test.cdppingpongservice",
  "packageFamilyName" : "5085ShawnHenry.RomanTestApp_jsjw7knzsgcce",
  "payload" : {
    "Type":"Toast","Title":"Hello","Subtitle":"World!"}
  }

Response

HTTP/1.1 201 OK

{
  "id": "0158355AD4D680CC4E2994CC009EFFD7EADA8307E96FF1C8D19B..",
  "status": "requesting",
  "type": null,
  "appServiceName": "com.microsoft.randomnumbergenerator",
  "packageFamilyName": "Microsoft.SDKSamples.AppServicesProvider.CS_8wekyb3d8bbwe",
  "error": null,
  "permissionTicket": null,
  "postBackUri": null,
  "payload": {
    "Type": "Toast",
    "Title": "Hello",
    "Subtitle": "World!"
  }
}