Compartilhar via

Acessar dados e métodos ao navegar no Microsoft Graph

Além de utilizar o Microsoft API do Graph para ler e escrever dados, pode utilizar vários padrões de pedido para percorrer os recursos no Microsoft Graph. O documento de metadados também ajuda a compreender 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. Pode ver o documento de serviço das versões v1.0 e beta do Microsoft API do Graph através dos seguintes URLs.

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. Geralmente, o formato de um ID de recurso 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, obterá uma resposta 200 OK que contém a coleção de recursos de utilizador no payload. Cada utilizador é identificado pela propriedade ID e acompanhado pelas respetivas propriedades predefinidas. O payload mostrado abaixo é truncado por 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 lhe permite ver coleções ao navegar nas relações de um recurso com outro. Por exemplo, através da propriedade de navegação mailFolders de um utilizador, pode consultar a coleção de recursos mailFolder na caixa de correio do utilizador:

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

Se for bem-sucedido, obterá uma resposta 200 OK que contém a coleção de recursos mailFolder no payload. Cada mailFolder é identificado pela propriedade ID e acompanhado pelas respetivas propriedades. O payload mostrado abaixo é truncado por 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, o 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",

    ...
}

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

Algumas entidades suportam uma chave alternativa, que pode utilizar para obter um objeto em vez do ID da chave primária. Por exemplo, as entidades application e servicePrincipal suportam a chave alternativa appId .

O exemplo seguinte utiliza a sintaxe de chave alternativa para obter um principal de serviço pelo respetivo 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 faz um pedido GET sem utilizar $select para limitar a quantidade de dados de propriedades, o Microsoft Graph inclui uma propriedade @microsoft.graph.tips que fornece uma recomendação de melhores práticas para utilizar $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

Pode obter uma única propriedade de um recurso sem utilizar $select, ao especificar o nome da propriedade como um segmento de caminho. Esta consulta não lhe permite obter várias propriedades, mas pode ser útil quando apenas precisa de uma única propriedade.

O exemplo seguinte obtém o displayName de um utilizador.

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 gestor mantém uma relação directReports com os outros utilizadores que 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 user-messages permite o percurso de um utilizador Microsoft Entra para um conjunto de mensagens de correio do Outlook. O exemplo seguinte mostra como fazê-lo numa chamada à 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"
}

Pode ver todas as funções disponíveis nos metadados. Aparecem como Funções ou Ações.

Usar os SDKs do Microsoft Graph

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

Conteúdo relacionado

  • Last updated on