Habilitar APIs e serviços limitados no Microsoft Graph

Algumas APIs e serviços no Microsoft Graph são limitados e exigem pagamento pelo uso. Para obter uma lista atualizada de APIs que exigem pagamento, consulte APIs e serviços limitados no Microsoft Graph.

Para consumir APIs e serviços limitados no Microsoft Graph, o registro do aplicativo para o aplicativo Microsoft Entra que consome as APIs deve ser associado a uma assinatura do Azure. Essa assinatura será cobrada por quaisquer encargos limitados. Essa associação também permite que você use o Gerenciamento de Custos do Azure + Cobrança para entender e gerenciar os custos do aplicativo.

Este artigo descreve como associar seu aplicativo a uma assinatura do Azure.

Limitações conhecidas

As seguintes limitações se aplicam a APIs limitadas:

• Atualmente, as APIs e os serviços limitados no Microsoft Graph estão disponíveis apenas no ambiente global da Microsoft e não em implantações de nuvem nacional, incluindo implantações do Microsoft 365 GCC acessadas por meio do ponto de extremidade mundial do Microsoft Graph. Para obter detalhes sobre nuvens nacionais, consulte Implantações de nuvem nacional.
• O aplicativo de destino deve ser um aplicativo cliente confidencial (por exemplo, aplicativo Web, API Web ou daemon/serviço). Não há suporte para aplicativos cliente públicos (aplicativos móveis e da área de trabalho).
• As identidades gerenciadas do Azure não têm suporte para chamar APIs limitadas. Para obter mais informações, consulte Serviços do Azure que dão suporte a identidades gerenciadas.

Pré-requisitos

Antes de acessar APIs e serviços limitados no Microsoft Graph, você deve concluir as seguintes etapas:

• Crie um registro de aplicativo no Microsoft Entra ID para o aplicativo que fará chamadas para as APIs e serviços limitados do Microsoft 365.
• Se você não tiver uma assinatura do Azure, crie uma agora no locatário que inclui o registro do aplicativo.
• Você deve ter permissões de contribuidor para a assinatura ativa do Azure que deseja usar, bem como permissões de proprietário do aplicativo para o registro do aplicativo de destino.

Habilitar um aplicativo

Para permitir que um aplicativo use APIs e serviços limitados no Microsoft Graph, ele deve ser associado a uma assinatura do Azure. Para criar essa associação, você deve criar um recurso do Azure do tipo Microsoft.GraphServices/accounts. O recurso do Azure conecta um único registro de aplicativo do Microsoft Entra com a assinatura do Azure em que o uso de APIs limitadas do aplicativo é cobrado.

Use as etapas a seguir para criar e vincular um recurso do Azure Microsoft.GraphServices/accounts ao seu aplicativo:

Observação: Você pode concluir as etapas a seguir entrando e escolhendo o https://portal.azure.comCloud Shell ou usando a interface de linha de comando do Azure local. Se você estiver usando o Cloud Shell pela primeira vez, talvez seja necessário criar uma conta de armazenamento. Selecione uma assinatura do Azure, escolha Criar e siga as instruções para criar uma conta de armazenamento. Para usar uma interface de linha de comando do Azure local, instale a CLI do Azure.

1. Se você tiver várias assinaturas do Azure, para obter informações sobre como definir a assinatura ativa, consulte Usar várias assinaturas do Azure; caso contrário, vá para a próxima etapa.

2. Use az graph-services no Azure Cloudshell ou sua própria instalação da CLI do Azure para criar uma nova instância do tipo de recurso Microsoft.GraphServices/accounts para associar o registro do aplicativo à assinatura ativa.

Copie o comando a seguir em sua interface de linha de comando preferida (PowerShell, Bash ou prompt de comando do Windows), substitua os parâmetros listados na tabela por seus próprios valores e digite <Enter>. Se o comando for bem-sucedido, a resposta incluirá uma representação JSON do recurso de cobrança recém-criado.

az graph-services account create --resource-group myRG  --resource-name myGraphAppBilling --subscription mySubscriptionGUID --location global --app-id AppRegGUID

Um resultado JSON bem-sucedido será semelhante a este:

{
  "extendedLocation": null,
  "id": "/subscriptions/<mySubscriptionGUID>/resourceGroups/<myRG>/providers/Microsoft.GraphServices/accounts/<myGraphAppBilling>",
  "identity": null,
  "kind": null,
  "location": "Global",
  "managedBy": null,
  "name": "<myGraphAppBilling>",
  "plan": null,
  "properties": {
    "appId": "<myAppGUID>",
    "billingPlanId": "123e4567-e89b-12d3-a456-426655440000",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "<myRG>",
  "sku": null,
  "systemData": {
    "createdAt": "2023-01-31T00:12:20.7893671Z",
    "createdByType": "User",
    "lastModifiedAt": "2023-01-31T00:12:20.7893671Z",
    "lastModifiedByType": "User"
  },
  "tags": null,
  "type": "microsoft.graphservices/accounts"
}

Verificar a configuração

Use as etapas a seguir para verificar se um aplicativo está habilitado corretamente para usar APIs e serviços limitados no Microsoft Graph.

Observação: Você pode concluir as etapas a seguir entrando e escolhendo o https://portal.azure.comCloud Shell ou usando a interface de linha de comando do Azure local. Se você estiver usando o Cloud Shell pela primeira vez, talvez seja necessário criar uma conta de armazenamento. Selecione uma assinatura do Azure, escolha Criar e siga as instruções para criar uma conta de armazenamento. Para usar uma interface de linha de comando do Azure local, instale a CLI do Azure.

1. Se você tiver várias assinaturas do Azure, para obter informações sobre como definir a assinatura ativa, consulte Usar várias assinaturas do Azure; caso contrário, vá para a próxima etapa.

2. Use az resource list para listar os recursos associados à assinatura ativa do Azure. Copie o seguinte comando na interface de linha de comando e digite <Enter>. Se o comando for bem-sucedido, a resposta incluirá uma representação JSON dos recursos associados à assinatura ativa do Azure.

  az resource list --resource-type Microsoft.GraphServices/accounts

Um resultado JSON bem-sucedido será semelhante a este:

[
  {
    "changedTime": "2023-04-25T18:12:30.586342+00:00",
    "createdTime": "2023-04-25T18:02:30.141407+00:00",
    "extendedLocation": null,
    "id": "/subscriptions/<mySubscriptionGUID>/resourceGroups/<myRG>/providers/Microsoft.GraphServices/accounts/<myGraphAppBilling>",
    "identity": null,
    "kind": null,
    "location": "global",
    "managedBy": null,
    "name": "<myGraphAppBilling>",
    "plan": null,
    "properties": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "<myRG>",
    "sku": null,
    "tags": null,
    "type": "Microsoft.GraphServices/accounts"
  }
]

3. Com os valores retornados na etapa 2, use az resource show para mostrar todos os detalhes do recurso. Copie o comando a seguir na interface de linha de comando, substitua os parâmetros listados na tabela pelos seus próprios valores e digite <Enter>. Se o comando for bem-sucedido, a resposta incluirá uma representação JSON do recurso solicitado.

  az resource show --resource-group myRg --name myGraphAppBilling --resource-type Microsoft.GraphServices/accounts

| Parameter | Description |
  |:--------------------------|:----------------------------------------|
  | myRG | The name of the Azure resource group provided in the result of step 2. |
  | myGraphAppBilling | The name of the resource provided in the result of step 2. |

  A successful JSON result will look something like this:

```json
{
  "extendedLocation": null,
  "id": "/subscriptions/<mySubscriptionGUID>/resourceGroups/<myRG>/providers/Microsoft.GraphServices/accounts/<myGraphAppBilling>",
  "identity": null,
  "kind": null,
  "location": "Global",
  "managedBy": null,
  "name": "<myGraphAppBilling>",
  "plan": null,
  "properties": {
    "appId": "<myAppGUID>",
    "billingPlanId": "123e4567-e89b-12d3-a456-426655440000"
  },
  "resourceGroup": "<myRG>",
  "sku": null,
  "tags": null,
  "type": "microsoft.graphservices/accounts"
}

A propriedade properties incluirá a ID do aplicativo do registro do aplicativo associado.

Consumir APIs limitadas em seu aplicativo

Depois de associar o registro e a assinatura do aplicativo, seu aplicativo poderá começar a usar APIs e serviços limitados no Microsoft Graph. Os custos gerados a partir dessas solicitações serão cobrados da assinatura do Azure associada ao aplicativo.

Observação: Seu aplicativo pode precisar solicitar um novo token de acesso OAuth antes que as solicitações para APIs limitadas sejam permitidas.

Você pode monitorar o custo e o uso de APIs e serviços limitados no Microsoft Graph por meio do Gerenciamento de Custos + Cobrança do Azure. Isso fornece acesso aos custos dentro da assinatura, que podem ser divididos com base no aplicativo, no locatário de chamada ou no medidor.

Faturas de API limitada e uso de serviço

Depois que o ciclo de cobrança da assinatura é executado, normalmente no 5º dia do mês, um proprietário de assinatura ou usuários com permissões baseadas em funções podem baixar uma fatura. Para obter detalhes, consulte Exibir e baixar sua fatura do Azure.

A fatura incluirá detalhes que permitem entender a quantidade de uso que seu aplicativo gera e, para aplicativos multilocatários, onde esse uso está acontecendo. Para obter detalhes, consulte Entender sua fatura do Azure.

Conteúdo relacionado

• Visão geral de APIs e serviços limitados no Microsoft Graph
• APIs e serviços limitados no Microsoft Graph
• APIs limitadas: perguntas frequentes