Compartilhar via

Acessar dados e métodos ao navegar no Microsoft Graph

  • Artigo

Além de usar o microsoft API do Graph para ler e gravar dados, você pode usar uma série de padrões de solicitação para percorrer os recursos no Microsoft Graph. O documento de metadados também ajuda você a entender o modelo de dados dos recursos e relações no Microsoft Graph.

Metadados da API do Microsoft Graph

O documento de metadados ($metadata) é publicado na raiz do serviço. Você pode exibir o documento de serviço para as versões v1.0 e beta do Microsoft API do Graph por meio das URLs a seguir.

Metadados 1.0 da API do Microsoft Graph

https://graph.microsoft.com/v1.0/$metadata

Metadados beta da API do Microsoft Graph

https://graph.microsoft.com/beta/$metadata

Com os metadados, você pode exibir e entender o modelo de dados do Microsoft Graph, inclusive os tipos de entidade, os tipos complexos e as enumerações que compõem os recursos representados nos pacotes de solicitação e resposta.

Os metadados também são compatíveis com os tipos, métodos e enumerações que os define em espaços de nomes (ou namespace),OData correspondentes. A maior parte da API do Microsoft Graph é definida no espaço de nomes OData, microsoft.graph. Algumas APIs são definidas em subnamespaces, por exemplo, microsoft.graph.callRecords.

Você pode usar os metadados para compreender as relações entre entidades no Microsoft Graph e estabelecer URLs que navegam entre essas entidades.

Observação

  • Use as IDs de recurso no mesmo caso de serem retornadas das APIs do Microsoft Graph.
  • Presuma que as IDs de recurso, valores atribuídos e outros valores codificados em base 64 diferenciam maiúsculas de minúsculas.
  • Presuma que os nomes de recursos do caminho da URL, parâmetros de consulta, nomes de ações e funções, solicitação de parâmetros de corpo, inclusive os nomes e valores da propriedade da API não diferenciam maiúsculas e minúsculas.

Exibir um conjunto de recursos

O Microsoft Graph permite exibir recursos em um locatário usando consultas HTTP GET. A resposta de consulta inclui as propriedades de cada recurso. Os recursos de entidade são todos identificados pela sua ID. O formato de uma ID de recurso geralmente varia de acordo com o tipo de recurso.

Por exemplo, você pode obter uma coleção de recursos de user definida no locatário:

GET https://graph.microsoft.com/v1.0/users HTTP/1.1
Authorization : Bearer {access_token}

Se for bem-sucedido, você receberá uma resposta de 200 OK que contém a coleção de recursos do usuário na carga. Cada usuário é identificado pela propriedade ID e acompanhado por suas propriedades padrão. A carga mostrada abaixo é truncada para brevidade.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "value":[
    {
      "id":"f71f1f74-bf1f-4e6b-b266-c777ea76e2c7",
      "businessPhones":[

      ],
      "displayName":"CIE Administrator",
      "givenName":"CIE",
      "jobTitle":null,
      "mail":"admin@contoso.com",
      "mobilePhone":"+1 3528700812",
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Administrator",
      "userPrincipalName":"admin@contoso.com"
    },
    {
      "id":"d66f2902-9d12-4ff8-ab01-21ec6706079f",
      "businessPhones":[

      ],
      "displayName":"Alan Steiner",
      "givenName":"Alan",
      "jobTitle":"VP Corporate Marketing",
      "mail":"alans@contoso.com",
      "mobilePhone":null,
      "officeLocation":null,
      "preferredLanguage":"en-US",
      "surname":"Steiner",
      "userPrincipalName":"alans@contoso.com"
    }
  ]
}

O Microsoft Graph também permite exibir coleções navegando nas relações de um recurso com outro. Por exemplo, por meio da propriedade de navegação mailFolders de um usuário, você pode consultar a coleção de recursos mailFolder na caixa de correio do usuário:

GET https://graph.microsoft.com/v1.0/me/mailfolders HTTP/1.1
Authorization : Bearer {access_token}

Se for bem-sucedido, você receberá uma resposta de 200 OK que contém a coleção de recursos mailFolder na carga. Cada mailFolder é identificado pela propriedade id e acompanhado por suas propriedades. A carga mostrada abaixo é truncada para brevidade.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('16f5a7b6-5a15-4568-aa5a-31bb117e9967')/mailFolders",
  "value":[
    {
      "id":"AAMkADRm9AABDGisXAAA=",
      "displayName":"Archive",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AQMkADRm0AAAIBXAAAAA==",
      "displayName":"Sales reports",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":0,
      "unreadItemCount":0,
      "totalItemCount":0
    },
    {
      "id":"AAMkADRCxI9AAAT6CAIAAA=",
      "displayName":"Conversation History",
      "parentFolderId":"AQMkADRmZWj0AAAIBCAAAAA==",
      "childFolderCount":1,
      "unreadItemCount":0,
      "totalItemCount":0
    }
  ]
}

Exibir um recurso específico de uma coleção pela ID

Para a maioria das entidades no Microsoft Graph, a id é a chave primária.

Para exibir as informações sobre um usuário, ainda com o uso do recurso user como exemplo, use uma solicitação GET HTTPS para chegar a um usuário específico pela ID do usuário. No caso de uma entidade user, você pode usar a propriedade id ou userPrincipalName como identificador.

A solicitação de exemplo a seguir usa o valor userPrincipalName como ID do usuário.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com HTTP/1.1
Authorization : Bearer {access_token}

Se tiver êxito, você obterá uma resposta 200 OK que contém a representação do recurso do usuário na carga, conforme mostrado.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 982

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id": "c95e3b3a-c33b-48da-a6e9-eb101e8a4205",
    "city": "Redmond",
    "country": "USA",
    "department": "Help Center",
    "displayName": "John Doe",
    "givenName": "John",
    "userPrincipalName": "john.doe@contoso.com",

    ...
}

Exibir um recurso específico de uma coleção por chave alternativa

Algumas entidades dão suporte a uma chave alternativa, que você pode usar para recuperar um objeto em vez da ID da chave primária. Por exemplo, as entidades de aplicativo e servicePrincipal dão suporte à chave alternativa appId .

O exemplo a seguir usa a sintaxe de chave alternativa para recuperar uma entidade de serviço por seu appId.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000') HTTP/1.1
Authorization : Bearer {access_token}

Ler propriedades específicas de um recurso

Para recuperar apenas os dados biográficos do usuário, conforme fornecido por ele na descrição Sobre mim, e suas habilidades, você pode adicionar o parâmetro de consulta $select à solicitação anterior, como mostrado no exemplo a seguir.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com?$select=displayName,aboutMe,skills HTTP/1.1
Authorization : Bearer {access_token}

A resposta bem-sucedida retorna o status 200 OK e uma carga, conforme mostrado.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 169

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "aboutMe": "A cool and nice guy.",
    "displayName": "John Doe",
    "skills": [
        "n-Lingual",
        "public speaking",
        "doodling"
    ]
}

Aqui, em vez de todos os conjuntos de propriedade na entidade user, somente as propriedades básicas aboutMe, displayName e skills são retornadas.

Quando você faz uma solicitação GET sem usar $select para limitar a quantidade de dados de propriedades, o Microsoft Graph inclui uma propriedade @microsoft.graph.tips que fornece uma recomendação de prática recomendada para usar $select semelhante à seguinte mensagem:

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

Ler apenas uma propriedade de um recurso

Você pode recuperar uma única propriedade de um recurso sem usar $select, especificando o nome da propriedade como um segmento de caminho. Essa consulta não permite que você recupere várias propriedades, mas pode ser útil quando você precisa apenas de uma única propriedade.

O exemplo a seguir recupera o displayName de um usuário.

GET https://graph.microsoft.com/beta/users/8afc02cb-4d62-4dba-b536-9f6d73e9be26/displayName HTTP/1.1
Authorization : Bearer {access_token}

Ler propriedades específicas dos recursos em uma coleção

Além de ler propriedades específicas de um único recurso, você também pode aplicar o parâmetro de consulta $select semelhante a uma coleção para obter todos os recursos na coleção com apenas as propriedades específicas retornadas em cada um.

Por exemplo, para consultar o nome dos itens na unidade do usuário conectado, você pode enviar a seguinte solicitação HTTPS GET.

GET https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name HTTP/1.1
Authorization : Bearer {access_token}

A resposta bem-sucedida retorna um código de status 200 OK e uma carga que contém apenas os nomes dos arquivos compartilhados, conforme mostrado no exemplo abaixo.

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/drive/root/children(name,type)",
  "value": [
    {
      "@odata.etag": "\"{896A8E4D-27BF-424B-A0DA-F073AE6570E2},2\"",
      "name": "Shared with Everyone"
    },
    {
      "@odata.etag": "\"{B39D5D2E-E968-491A-B0EB-D5D0431CB423},1\"",
      "name": "Documents"
    },
    {
      "@odata.etag": "\"{9B51EA38-3EE6-4DC1-96A6-230E325EF054},2\"",
      "name": "newFile.txt"
    }
  ]
}

Passar de um recurso para outro pela relação

Um gerente mantém uma relação directReports com os outros usuários que se reportam a ele ou a ela. Para consultar a lista de subordinados de um usuário, você pode usar a solicitação HTTPS GET a seguir para navegar para o destino pretendido via passagem de relação.

GET https://graph.microsoft.com/v1.0/users/john.doe@contoso.com/directReports HTTP/1.1
Authorization : Bearer {access_token}

A resposta bem-sucedida retorna o status 200 OK e uma carga, conforme mostrado.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
content-length: 152

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects/$entity",
    "@odata.type": "#microsoft.graph.user",
    "id": "c37b074d-fe9d-4e68-83ad-b4401d3be174",
    "department": "Sales & Marketing",
    "displayName": "Bonnie Kearney",

    ...
}

Da mesma forma, você pode seguir um relacionamento para navegar até os recursos relacionados. Por exemplo, a relação entre mensagens de usuário permite a travessia de um usuário Microsoft Entra para um conjunto de mensagens de email do Outlook. O exemplo a seguir mostra como fazer isso em uma chamada de API REST.

GET https://graph.microsoft.com/v1.0/me/messages HTTP/1.1
Authorization : Bearer {access_token}

A resposta bem-sucedida retorna o status 200 OK e uma carga, conforme mostrado.

HTTP/1.1 200 OK
content-type: application/json;odata.metadata=minimal
odata-version: 4.0
content-length: 147

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('john.doe%40contoso.com')/Messages",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$top=1&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej\"",
      "id": "<id-value>",
      "createdDateTime": "2015-11-14T00:24:42Z",
      "lastModifiedDateTime": "2015-11-14T00:24:42Z",
      "changeKey": "FwAAABYAAABMR67yw0CmT4x0kVgQUH/3AAJL+Kej",
      "categories": [],
      "receivedDateTime": "2015-11-14T00:24:42Z",
      "sentDateTime": "2015-11-14T00:24:28Z",
      "hasAttachments": false,
      "subject": "Did you see last night's game?",
      "body": {
        "ContentType": "HTML",
        "Content": "<content>"
      },
      "BodyPreview": "it was great!",
      "Importance": "Normal",

       ...
    }
  ]
}

Você pode ver todas as relações em um determinado recurso indo para os metadados, localizando EntityType e examinando todas asNavigationProperty do EntityType.

Funções e ações de chamada

O Microsoft Graph também oferece suporte a ações e funções para manipular recursos de maneiras que não são apenas operações de criar, ler, atualizar e excluir (CRUD). Eles normalmente estão na forma de solicitações de HTTPS POST para receber argumentos para ação e função. Por exemplo, a seguinte ação permite que o usuário conectado (me) envie uma mensagem de email.

POST https://graph.microsoft.com/v1.0/me/sendMail HTTP/1.1
authorization: bearer {access_token}
content-type: application/json
content-length: 96

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "garthf@contoso.com"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "microsoft.graph.fileAttachment",
        "name": "menu.txt",
        "contentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
      }
    ]
  },
  "saveToSentItems": "false"
}

Você pode ver todas as funções disponíveis nos metadados. Elas aparecem como Funções ou Ações.

Usar os SDKs do Microsoft Graph

Como o poder e a facilidade dos SDKs? Embora você sempre possa usar APIs REST para chamar o Microsoft Graph, também fornecemos SDKs para muitas plataformas populares. Para explorar os SDKs disponíveis, consulte Exemplos de código e SDKs.

Conteúdo relacionado