Enviar comando de dispositivo (preterido)

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Cuidado

Essa API foi preterida e parou de retornar dados em 30 de setembro de 2020.

Essa API permite que os recursos do Project Rome comandem um dispositivo associado a uma conta Microsoft. Depois de fazer uma chamada GET, me/devicespasse a ID do dispositivo para emitir um comando para seu dispositivo. Há suporte para dois tipos de comandos: LaunchURI e AppServices. Se você estiver usando o LaunchURI, especifique os parâmetros de tipo e carga . Para uma chamada appService, especifique os parâmetros tipo, carga, packageFamilyName e appServiceName .

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global	Governo dos EUA L4	GOVERNO DOS EUA L5 (DOD)	China operada pela 21Vianet
✅	❌	❌	❌

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão	Permissões menos privilegiadas	Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante)	Sem suporte.	Sem suporte.
Delegado (conta pessoal da Microsoft)	Device.Command	Indisponível.
Aplicativo	Sem suporte.	Sem suporte.

Solicitação HTTP

POST me/devices/{id}/commands

Cabeçalhos de solicitação

Cabeçalho	Valor
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Aceitar	application/json

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON das propriedades de comando.

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

Resposta

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

Propriedades de comando

Nome	Tipo	Descrição
payload	microsoft.graph.json	Carregar para enviar para um serviço de aplicativo ou para iniciar um URI em um dispositivo.
responsePayload	microsoft.graph.json	Carga retornada do dispositivo de destino.
postBackURI	Cadeia de caracteres	Poste o URI de volta para enviar notificações subsequentes de atualizações.
packageFamilyName	Cadeia de caracteres	Nome da família de pacotes do Windows do aplicativo.
appServiceName	Cadeia de caracteres	Nome do serviço de aplicativo definido pelo aplicativo de destino. Necessário se iniciar um serviço de aplicativo.
type	Cadeia de caracteres	LaunchURI ou AppService.
id	Cadeia de caracteres	A ID de um comando que foi enviado para o dispositivo.
actionStatus	Cadeia de caracteres	O status de um comando.
erro	Cadeia de caracteres	Quaisquer erros associados à solicitação do aplicativo de destino.

Exemplos

Exemplo 1: Iniciar o URI

A seguir está um exemplo de uma solicitação LaunchURI; ele iniciará um URI ou um aplicativo no dispositivo de destino. Para iniciar um URI ou um aplicativo, emita um POST usando a ID do dispositivo (obtido de fazer uma chamada GET em me/devices). Defina os parâmetros Type como LaunchURI e forneça um valor de URI, como https://bing.com.

Solicitação

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

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

Resposta

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

Exemplo 2: Serviço de aplicativo

O exemplo a seguir mostra como consultar um serviço de aplicativo em um dispositivo. Para usar um serviço de aplicativo, você deve fazer uma chamada POST usando a ID do dispositivo (obtida com a chamada GET ).me/devices Para usar o exemplo a seguir, você deve instalar o aplicativo Rome em seu dispositivo de destino.

Várias propriedades adicionais devem ser definidas na chamada. O tipo deve ser definido como AppService, AppServiceName deve ser definido como o nome do serviço de aplicativo definido no aplicativo, PackageFamilyName deve ser definido como o nome da família do pacote definido no manifesto do aplicativo e o Payload contém as chaves e os valores do serviço que você está chamando dentro do aplicativo de destino.

Solicitação

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

Resposta

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