Ativar APIs e serviços com tráfego limitado no Microsoft Graph
Algumas APIs e serviços no Microsoft Graph têm tráfego limitado e exigem o pagamento para utilização. Para obter uma lista atual de APIs que requerem pagamento, veja APIs e serviços medidos no Microsoft Graph.
Para consumir APIs e serviços limitados no Microsoft Graph, o registo da aplicação Microsoft Entra que consome as APIs tem de estar associado a uma subscrição do Azure. Esta subscrição será faturada por quaisquer custos limitados. Esta associação também lhe permite utilizar o Azure Cost Management + Faturação para compreender e gerir os custos da aplicação.
Este artigo descreve como associar a sua aplicação a uma subscrição do Azure.
Limitações conhecidas
As seguintes limitações aplicam-se às APIs com tráfego limitado:
- Atualmente, as APIs e serviços medidos no Microsoft Graph estão disponíveis apenas no ambiente global da Microsoft e não em implementações na cloud nacionais, incluindo implementações do Microsoft 365 GCC acedidas através do ponto final mundial do Microsoft Graph. Para obter detalhes sobre clouds nacionais, veja Implementações de cloud nacionais.
- A aplicação de destino tem de ser uma aplicação cliente confidencial (por exemplo, aplicação Web, API Web ou daemon/serviço). As aplicações cliente públicas (aplicações móveis e de ambiente de trabalho) não são suportadas.
- As identidades geridas do Azure não são suportadas para chamar APIs com tráfego limitado. Para obter mais informações, veja Serviços do Azure que suportam identidades geridas.
Pré-requisitos
Antes de poder aceder a APIs e serviços limitados no Microsoft Graph, tem de concluir os seguintes passos:
- Crie um registo de aplicação no Microsoft Entra ID para a aplicação que irá efetuar chamadas para as APIs e serviços do Microsoft 365 com tráfego limitado.
- Se não tiver uma subscrição do Azure, crie uma agora no inquilino que inclua o registo da aplicação.
- Tem de ter permissões de contribuidor para a subscrição ativa do Azure que pretende utilizar, bem como permissões de proprietário da aplicação para o registo da aplicação de destino.
Ativar uma aplicação
Para permitir que uma aplicação utilize APIs e serviços limitados no Microsoft Graph, tem de estar associada a uma subscrição do Azure. Para criar esta associação, tem de criar um recurso do Azure do tipo Microsoft.GraphServices/accounts. O recurso do Azure liga um único registo da aplicação Microsoft Entra à subscrição do Azure onde a utilização da aplicação de APIs com tráfego limitado é faturada.
Utilize os seguintes passos para criar e ligar um recurso do Microsoft.GraphServices/accounts do Azure à sua aplicação:
Nota: Pode concluir os seguintes passos ao iniciar sessão https://portal.azure.com e escolher o Cloud Shell ou através da interface de linha de comandos local do Azure. Se estiver a utilizar o Cloud Shell pela primeira vez, poderá ter de criar uma conta de armazenamento. Selecione uma subscrição do Azure, selecione Criar e siga as instruções para criar uma conta de armazenamento. Para utilizar uma interface de linha de comandos local do Azure, instale a CLI do Azure.
Se tiver várias subscrições do Azure, para obter informações sobre como definir a subscrição ativa, veja Utilizar várias subscrições do Azure; caso contrário, avance para o passo seguinte.
Utilize az graph-services no Azure Cloudshell ou a 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 registo da aplicação à subscrição ativa.
Copie o seguinte comando para a interface de linha de comandos preferida (PowerShell, Bash ou linha de comandos do Windows), substitua os parâmetros listados na tabela pelos seus próprios valores e escreva <Enter>. Se o comando for bem-sucedido, a resposta inclui uma representação JSON do recurso de faturação recentemente criado.
az graph-services account create --resource-group myRG --resource-name myGraphAppBilling --subscription mySubscriptionGUID --location global --app-id AppRegGUID
| Parâmetro | Descrição |
|---|---|
| myRG | O nome de um grupo de recursos do Azure existente ao qual adicionar o recurso recentemente criado. |
| myGraphAppBilling | O nome que pretende dar a esta instância de recurso. |
| myAppGUID | O ID da Aplicação (cliente) da aplicação que está a ser ativada, fornecido como um parâmetro de cadeia; por exemplo, 123e4567-e89b-12d3-a456-426655440000. |
| mySubscriptionGUID | O ID da subscrição do Azure que irá receber eventos de faturação, fornecidos como um parâmetro de cadeia; por exemplo, 123e4567-e89b-12d3-a456-426655440000. |
Um resultado JSON com êxito terá um aspeto semelhante ao seguinte:
{
"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
Utilize os seguintes passos para verificar se uma aplicação está devidamente ativada para utilizar APIs e serviços com tráfego limitado no Microsoft Graph.
Nota: Pode concluir os seguintes passos ao iniciar sessão https://portal.azure.com e escolher o Cloud Shell ou através da interface de linha de comandos local do Azure. Se estiver a utilizar o Cloud Shell pela primeira vez, poderá ter de criar uma conta de armazenamento. Selecione uma subscrição do Azure, selecione Criar e siga as instruções para criar uma conta de armazenamento. Para utilizar uma interface de linha de comandos local do Azure, instale a CLI do Azure.
Se tiver várias subscrições do Azure, para obter informações sobre como definir a subscrição ativa, veja Utilizar várias subscrições do Azure; caso contrário, avance para o passo seguinte.
Utilize az resource list para listar os recursos associados à subscrição ativa do Azure. Copie o seguinte comando para a interface de linha de comandos e escreva <Enter>. Se o comando for bem-sucedido, a resposta incluirá uma representação JSON dos recursos associados à subscrição ativa do Azure.
az resource list --resource-type Microsoft.GraphServices/accounts
Um resultado JSON com êxito terá um aspeto semelhante ao seguinte:
[
{
"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"
}
]
- Com os valores devolvidos no passo 2, utilize az resource show para mostrar todos os detalhes do recurso. Copie o seguinte comando para a interface de linha de comandos, substitua os parâmetros listados na tabela pelos seus próprios valores e escreva <Enter>. Se o comando for bem-sucedido, a resposta incluirá uma representação JSON do recurso pedido.
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á o ID da aplicação do registo de aplicação associado.
Consumir APIs com tráfego limitado na sua aplicação
Depois de associar o registo da aplicação e a subscrição, a sua aplicação pode começar a utilizar APIs e serviços com tráfego limitado no Microsoft Graph. Os custos gerados a partir desses pedidos serão cobrados à subscrição do Azure associada à aplicação.
Nota: A sua aplicação poderá ter de pedir um novo token de acesso OAuth antes de os pedidos às APIs com tráfego limitado serem permitidos.
Pode monitorizar o custo e a utilização de APIs e serviços medidos no Microsoft Graph através do Azure Cost Management + Faturação. Isto fornece acesso aos custos na subscrição, que podem ser divididos com base na aplicação, no inquilino ou no medidor de chamadas.
Faturas da API com tráfego limitado e da utilização do serviço
Após a execução do ciclo de faturação da subscrição, normalmente no 5º dia do mês, um proprietário da subscrição ou utilizadores com permissões baseadas em funções podem transferir uma fatura. Para obter detalhes, veja Ver e transferir a fatura do Azure.
A fatura incluirá detalhes que lhe permitem compreender a quantidade de utilização gerada pela sua aplicação e para aplicações multi-inquilino, onde essa utilização está a ocorrer. Para obter detalhes, veja Compreender a fatura do Azure.