已弃用) (发送设备命令

项目
04/18/2024

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。不支持在生产应用程序中使用这些 API。若要确定 API 是否在 v1.0 中可用，请使用版本选择器。

警告

2020 年 9 月 30 日，此 API 已弃用并停止返回数据。

此 API 使 Project Rome 功能能够命令与 Microsoft 帐户关联的设备。在上 me/devices执行 GET 调用后，传入设备的 ID，以便向设备发出命令。支持两种类型的命令：LaunchURI 和 AppServices。如果使用 LaunchURI，请指定类型和有效负载参数。对于 AppService 调用，请指定类型、 有效负载、 packageFamilyName 和 appServiceName 参数。

此 API 可用于以下国家级云部署。

全局服务	美国政府 L4	美国政府 L5 (DOD)	由世纪互联运营的中国
✅	❌	❌	❌

权限

为此 API 选择标记为最低特权的权限。只有在应用需要它时，才使用更高的特权权限。有关委派权限和应用程序权限的详细信息，请参阅权限类型。要了解有关这些权限的详细信息，请参阅权限参考。

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	不支持。	不支持。
委派（个人 Microsoft 帐户）	Device.Command	不可用。
应用程序	不支持。	不支持。

HTTP 请求

POST me/devices/{id}/commands

请求标头

标头	值
Authorization	持有者 {token}。必填。详细了解身份验证和授权。
接受	application/json

请求正文

在请求正文中，提供命令属性的 JSON 表示形式。

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

响应

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"
}

命令属性

名称	类型	说明
payload	microsoft.graph.json	要发送到应用服务或在设备上启动 URI 的有效负载。
responsePayload	microsoft.graph.json	从目标设备返回的有效负载。
postBackURI	String	回发 URI 以发送后续更新通知。
packageFamilyName	String	应用程序的 Windows 程序包系列名称。
appServiceName	String	目标应用程序定义的应用服务的名称。启动应用服务时是必需的。
type	String	LaunchURI 或 AppService。
id	String	已发送到设备的命令的 ID。
actionStatus	String	命令的状态。
error	String	与来自目标应用程序的请求关联的任何错误。

示例

示例 1：启动 URI

下面是 LaunchURI 请求的示例：它将在目标设备上启动 URI 或应用程序。若要启动 URI 或应用，请使用在) 上执行 GET 调用 me/devices (获取的设备 ID 发出 POST。将 Type 参数设置为 LaunchURI 并提供 URI 值，例如 https://bing.com。

请求


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

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

响应

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"
  }
}

示例 2：应用服务

以下示例演示如何在设备上查询应用服务。若要使用应用服务，必须使用在) 上执行 GET 调用 (获取的设备 ID 执行 POST 调用 me/devices 。若要使用以下示例，必须在目标设备上安装 Rome 应用。

必须在调用中设置多个附加属性。类型必须设置为 AppService，AppServiceName 必须设置为应用程序中定义的应用服务的名称，PackageFamilyName 必须设置为在应用清单中定义的包系列名称，有效负载保存你在目标应用程序中调用的服务的键和值。

请求


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!"}
  }

响应

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!"
  }
}