Descrição geral da API do Cloud for Sustainability (pré-visualização)

O Microsoft Cloud for Sustainability fornece API para aceder a dados de emissões relacionados com a sua utilização de Azure e do Microsoft 365.

A gestão contabilística precisa do carbon exige boas informações dos parceiros, fabricantes e fornecedores. As APIs da Cloud for Sustainability fornecem-lhe transparência sobre as emissões de carbono geradas pela sua utilização do Azure e do Microsoft 365. A gestão contabilística de carbono da Microsoft estende-se pelos três âmbitos de emissões com uma metodologia validada pelor terceiros. Utiliza gestão contabilística consistente e precisa de carbono para quantificar o efeito de Azure e do Microsoft 365 na quantidade ambiental do cliente.

Os detalhes da API estão listadps na Microsoft Cloud for Sustainability referência de API. Incluem informações adicionais sobre operações, parâmetros e respostas.

• Introdução às API com o Cloud for Sustainability
• Consultas de amostra
• Atribuir permissões
• Gerir instâncias
• Ver utilização da API
• FAQ

Introdução às API do Cloud for Sustainability

Introdução às API com os seguintes procedimentos:

• Rever as contas suportadas
• Iniciar sessão e criar uma instância
• Configurar as origens de dados e ativar as API
• Experimentar as API

Contas suportadas

• Azure: As API do Microsoft Cloud for Sustainability para Azure suportam contas EA Direct, MCA e MPA com relações de faturação direta com a Microsoft. Os clientes que adquirirem Azure a partir de um Fornecedor de Solução Cloud (CSP) não são suportados e têm de trabalhar diretamente com o CSP para saberem mais sobre as suas emissões de cloud. As contas legadas, as contas baseadas em créditos, as inscrições da China e as contas do Azure Government não são suportadas. Para verificar o seu tipo de conta, aceda a Verificar o tipo da sua conta.

  Nota

  A utilização do Benefício Híbrido do Azure não é atualmente capturada ou refletida nas emissões.

• Microsoft 365 : as APIs do Microsoft Cloud for Sustainability para Microsoft 365 suportam subscrições business, enterprise ou education para o Microsoft 365 ou o Office 365. Não são suportadas implementações de cloud nacionais/regionais, incluindo, sem limitação, clouds da Administração Pública dos EUA da Microsoft e do Office 365 operado pela 21Vianet.

Iniciar sessão e criar uma instância

Depois de receber acesso às APIs do Microsoft Cloud for Sustainability da Microsoft, inicie sessão com as suas credenciais do ID do Microsoft Entra do Azure.

Tem de criar uma instância para aceder às API do Microsoft Cloud for Sustainability. Ao criar a instância, torna-se no administrador dessa instância. O administrador da instância pode adicionar utilizadores, grupos e aplicações à instância.

Veja este vídeo para uma conhecer descrição geral sobre a utilização de APIs da Cloud for Sustainability e o portal:

Configurar origens de dados e ativar as API

1. No separador Origens de Dados, defina a ligação como ativado para ligar os dados de emissões de Azure e do Microsoft 365. Certifique-se de que o estado está listado como Disponível antes de utilizar as API. Esta ação ativa os dados de emissões relacionados com todas as inscrições ou contas de faturação para as quais tem acesso. Se não tiver acesso a quaisquer dados de emissões, prossiga apenas com os dados de demonstração.

   Nota

   Pode demorar até 48 horas para que os dados de emissões do Microsoft 365 fiquem disponíveis depois de ativar a origem de dados. A desativação da origem de dados do Microsoft 365 eliminará permanentemente dados de emissões históricos do Microsoft 365.

   

2. Selecione o separador Gestão de API e, em seguida, selecione Ativar.

   A ativação da API gera chaves de API primárias e secundárias para a sua instância utilizar em pedidos de API. Para regenerar as chaves, selecione . Para copiar as chaves, selecione .

Está interessado em configurar uma aplicação para chamar a API da Cloud for Sustainability? Veja esta demonstração:

Experimentar as API

No separador Gestão de API, selecione Experimentar a API para explorar APIs OData e de Exportação. Consulte interativamente os seus dados de emissões ao ligar APIs de OData de baixa latência para os seus dashboards. Ou efetue o seu próprio processamento em massa transferindo os seus dados de emissões diretamente para o seu Azure Data Lake Storage utilizando APIs de Exportação. Um portal do programador é aberto num novo separador, onde pode explorar os esquemas de pedidos e respostas e fazer pedidos em direto em relação às APIs do Microsoft Cloud for Sustainability.

Experimentar APIs OData

1. Na navegação à esquerda, certifique-se de que Agrupar por etiqueta está ativado e selecione o agrupamento OData para rever as APIs OData do Azure e do Microsoft 365.

2. Para fazer um pedido em direto, selecione Experimentar. Introduza todos os campos obrigatórios:

   • Autorização: token de autorização povoado automaticamente
   • Chave de subscrição: povoada automaticamente com a chave de API do separador Gestão de API
   • enrollmentId: a sua ID de inscrição , também conhecida como ID de conta de faturação. Azure apenas. Se não tiver acesso a uma inscrição, poderá explorar a API utilizando dados de demonstração ao introduzir dados de demonstração neste campo.
   • instanceId: encontrada no URL do portal de API do Microsoft Cloud for Sustainability
   • tenantId: ID do inquilino do Microsoft 365.

   

3. Adicione todos os pârametros de consulta necessários. Percorra a parte inferior do painel lateral e selecione Enviar. A resposta HTTP é apresentada no fundo do painel.

Veja a este vídeo para obter mais informações sobre as APIs da Cloud for Sustainability com OData:

Experimentar APIs de Exportação

1. Na navegação à esquerda, certifique-se de que Agrupar por etiqueta está ativado e selecione o agrupamento de Exportação para começar a exportar dados de emissões e de utilização para o seu data lake. Selecione RunExportJob.

2. Selecione Experimentar. Introduza todos os campos obrigatórios e selecione Enviar.

   • Autorização: token de autorização povoado automaticamente
   • Chave de subscrição: povoada automaticamente com a chave de API do separador Gestão de API
   • instanceId: encontrada no URL do portal de API do Microsoft Cloud for Sustainability
   • exportJobType: selecione o Azure ou o Microsoft 365 para designar a origem de dados para os dados de emissão e de utilização a exportar.
   • dados de demonstração: introduza "true" se pretender explorar esta funcionalidade exportando dados de demonstração.

3. Depois de selecionar Enviar, desloque-se para baixo para ver a resposta HTTP. Se estiver a exportar dados do Azure, a resposta enumera os IDs de inscrição para os dados exportados. Se não tiver acesso a dados do Azure ou do Microsoft 365, esta operação não tem êxito. Certifique-se de que configurou corretamente as suas origens de dados.

   Inicialmente, a resposta indica que a tarefa contém NotStarted. A tarefa de exportação demora 2 a 3 minutos a ser concluída, sendo possível utilizar o jobID para verificar o estado da exportação utilizando a API ExportJobStatus. Certifique-se de que a tarefa foi concluída com êxito, o que indica que os dados exportados estão agora disponíveis no armazenamento de blobs de teste.

   Pode utilizar LatestExportJob para rever informações relativas à última tarefa de exportação.

   Pode utilizar a API ExportJobs para rever informações relativas às exportações históricas.

4. Utilize a API ExportLocation para obter o URL da SAS. O URL de SAS expirará após uma hora. Copie o URL da SAS para aceder aos dados exportados a partir do armazenamento de blobs de teste.

5. Os dados estão definidos para expirar 28 dias após a tarefa de exportação ser executada e têm de ser copiados antes da expiração. Caso contrário, os dados são eliminados da localização de teste. Os utilizadores podem voltar a executar uma tarefa de exportação a qualquer momento para obterem outro lote de dados com uma expiração de 28 dias e incluindo o mais recente conjunto de dados. Existem algumas maneiras de aceder aos dados exportados.

   1. Explorador de Armazenamento do Azure

      Instale e abra o Explorador de Armazenamento do Azure. Selecione o botão Abrir o Diálogo de Ligação e, em seguida, selecione Contentor ou diretório do ADLS Gen2. Selecione URL da assinatura de acesso partilhado (SAS) e cole o URL da SAS do passo 4 para a entrada Contentor ou diretório de blobs do URL da SAS. Selecione Seguinte e, em seguida, selecione Ligar. Precisa de localizar ou criar um contentor numa conta de armazenamento nova ou existente a utilizar para armazenar estes dados exportados. Copie os dados do Azure ou do Microsoft 365 do armazenamento de blobs de teste e cole no contentor à sua escolha.

   2. Utilize azcopy. Utilizando o URL da SAS do passo 4 e o URL da conta de armazenamento onde está a armazenar as suas emissões exportadas (URL de destino), execute o comando azcopy.exe:

      • azcopy login
      • azcopy list <SAS URL>
      • azcopy cp <SAS URL> <destination URL>

   3. Script do Spark

      Utilize mssparkutils no Microsoft Fabric ou Synapse. Pode optar por utilizar bibliotecas e ambientes alternativos.

      import subprocess
      from notebookutils import mssparkutils
      
      result = subprocess.run(['pip', 'install', 'azure-storage-blob'], capture_output=True)
      
      # replace with SAS URI from API request
      source_sas_url = 'https://<account_name>.blob.windows.net/<container_name>/<path>?<sas_token>'
      
      start_index = source_sas_url.find('https://') + len('https://')
      end_index = source_sas_url.find('.blob', start_index)
      account_name = source_sas_url[start_index:end_index]
      split = source_sas_url.split('?', 1)
      domain_path = split[0]
      sas_token = split[1]
      container_name = domain_path.split('/')[3]
      
      source_mount_point = '/src'
      destination_mount_point = '/dest'
      
      mssparkutils.fs.unmount(source_mount_point)
      mssparkutils.fs.mount(
          f'abfss://{container_name}@{account_name}.blob.core.windows.net',
          source_mount_point,
          { 'sasToken': sas_token })
      
      mssparkutils.fs.unmount(destination_mount_point)
      mssparkutils.fs.mount( 
          'abfss://<destinationPath>', # replace with destination connection string
          destination_mount_point)
      
      mssparkutils.fs.cp(src_path, dest_path, True)
      

Consultas de amostra

Para uma pequena lista de consultas de amostra OData para trabalhar com as API, aceda a Exemplos de consultas OData.

Atribuir permissões

O acesso às APIs do Microsoft Cloud for Sustainability está restrito aos utilizadores na organização que um admin de uma instância adiciona à aplicação. Um utilizador pode ser um único utilizador, um grupo ou uma aplicação. As contas de convidados não são suportadas. Existem três tipos de funções que pode atribuir:

• Visualizador: pode ver todas as páginas na API do Microsoft Cloud for Sustainability.
• Contribuidor: pode interagir com todas as páginas no portal de API do Microsoft Cloud for Sustainability. Não pode adicionar ou remover utilizadores.
• Administrador: todas as permissões disponíveis, incluindo a capacidade de adicionar ou remover utilizadores.

Para adicionar utilizadores, grupos ou aplicações como administrador:

1. Selecione o separador Permissões e, em seguida, selecione Adicionar Utilizadores.
2. Utilize o campo Pesquisar para encontrar o utilizador, grupo ou aplicação do ID do Microsoft Entra que pretende adicionar.
3. Selecione uma atribuição de função e, em seguida, selecione Guardar.

Gerir instâncias

Navegue para o ícone de instância para localizar uma lista de todas as instâncias, criar instâncias ou remover instâncias.

Ver utilização da API

Ver detalhes sobre a sua uilização da API em tempo real.

1. Navegue para o separador Gestão de API e, em seguida, selecione Utilização.
2. Selecione um intervalo de tempo a ver.

A página Utilização da API contém três secções:

• Chamadas à API: um gráfico que visualiza o número agregado de chamadas à API no intervalo de tempo selecionado.
• Transferência de dados: um gráfico que mostra a quantidade de dados que foram transferidos através da API no intervalo de tempo selecionado.
• Operações: uma tabela com linhas para cada operação API disponível e detalhes sobre a utilização das operações.

FAQ

Como é que a Microsoft calcula as emissões de carbono da cloud disponibilizadas pela API?

Para obter informações sobre a metodologia de cálculo da Microsoft, aceda a Microsoft Cloud for Sustainability metodologia de cálculo da API.

Onde posso saber mais sobre como escrever consultas com OData?

Para saber mais sobre OData, aceda a Descrição geral das opções de consulta.

Onde é que os dados utilizados para produzir este relatório são armazenados?

Os dados são armazenados nos Estados Unidos.

Porque é que não consigo ver os dados de emissões do mês anterior?

Os dados de emissões de um determinado mês estarão disponíveis até ao 14.º dia após o fim desse mês (incluindo dias não úteis).

Não consigo criar uma instância. Porquê?

Pode estar a tentar aceder ao portal da API da Cloud for Sustainability com uma conta associada a um ID de inquilino diferente do fornecido no formulário de inclusão. Esta situação pode ocorrer quando utiliza uma conta de convidado. As contas de convidados não são suportadas. Se pretender que incluamos outro inquilino, volte a submeter o formulário de inclusão.

Tenho um ID de inquilino diferente para o Microsoft 365 e Azure. Posso continuar a utilizar a API do Microsoft Cloud for Sustainability?

Ainda pode aceder às APIs, mas o portal não suporta vários inquilinos por instância. Terá de incluir estes inquilinos nas APIs separadamente.

Como configurar uma aplicação para chamar a API do Microsoft Cloud for Sustainability?

Está interessado em configurar uma aplicação para chamar a API da Cloud for Sustainability? Veja esta demonstração:

No portal do Azure, aceda ao seu ID do Microsoft Entra, selecione Registos de aplicações e, em seguida, + Novo registo. Na nova página de registo, dê um nome ao registo da aplicação, personalize opções de acordo com as suas necessidades e, em seguida, selecione Registar. Aceda à página do ID do Microsoft Entra, selecione o friso Aplicações empresariais, defina Tipo de aplicação como Aplicações Microsoft e pesquise pelo nome da aplicação MCFS SDS. O parâmetro ApplicationId que transmitiu no comando New-AzADServicePrincipal necessário durante a inclusão é o ApplicationId da API do Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9) com a qual criou uma instância (aplicação empresarial) do registo de aplicação da API do Microsoft Cloud for Sustainability no seu próprio inquilino.

Com isso em vigor, pode agora aceder à sua página de registo de aplicação e selecionar o friso Permissões da API. Para adicionar permissão para que o seu registo de aplicação possa chamar a API do Microsoft Cloud for Sustainability, selecione + Adicionar uma permissão, seguido da opção APIs que a minha organização utiliza. Em seguida, pesquise pelo ApplicationId da API do Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), selecione MCFS SDS e, em seguida, selecione a permissão App.Emissions.Read do friso Permissões da aplicação.

Esta permissão de tipo de aplicação tem de receber o consentimento do administrador selecionando Conceder consentimento do administrador a {your-tenant}.

Por último, visite a home page da API do Microsoft Cloud for Sustainability, navegue para o friso Permissões e, em seguida, selecione + Adicionar. No painel lateral que aparece, escolha Visualizador como a Função na entrada de Utilizador, Grupo ou Aplicação e prossiga para pesquisar pelo seu registo de aplicação. Selecione Guardar.

Estou a obter um token de acesso para a minha aplicação, o que é o URL do recurso?

c3163bf1-092f-436b-b260-7ade5973e5b9/.default

Quanto dados históricos estão disponíveis?

• Azure: os dados de utilização e de emissões abrangem os últimos cinco anos de dados associados ao processo de inscrição.
• Microsoft 365 os dados de emissões abrangem os últimos 12 meses de dados associados à subscrição do Microsoft 365.

Exclusão de Responsabilidade

A API do Microsoft Cloud for Sustainability (pré-visualização) baseia-se nas normas do setor para o cálculo de carbono de servidores. Fornece estimativas gerais para ajudar as organizações a obterem informações das emissões de carbono da infraestrutura de TI associada à utilização de serviços Cloud do Azure. As descobertas, interpretações e conclusões apresentadas com a API do Microsoft Cloud for Sustainability (pré-visualização), incluindo os cálculos, não são conselhos nem recomendações específicos. As informações e as opiniões expressas podem ser mudadas sem aviso prévio. A API do Microsoft Cloud for Sustainability (pré-visualização) é fornecida tal como está, sem qualquer representação ou garantia de qualquer tipo, expressa ou implícita, incluindo, sem limitação, qualquer representação ou endossos relativamente à utilização de, aos resultados de, ou ao desempenho da API do Microsoft Cloud for Sustainability (pré-visualização), a sua adequação, precisão, fiabilidade ou exatidão. O risco completo relativo à utilização da API do Microsoft Cloud for Sustainability (pré-visualização) é assumido por si. A Microsoft não assume a responsabilidade pela utilização da API do Microsoft Cloud for Sustainability (pré-visualização). Em nenhum caso a Microsoft será responsável por outros danos diretos ou indiretos, incluindo qualquer perda de lucros, perda de poupanças ou quaisquer danos incidentais ou consequenciais provenientes de quaisquer defeitos ou a utilização ou a incapacidade de usar a API do Microsoft Cloud for Sustainability (pré-visualização), mesmo que a Microsoft tenha sido avisada da possibilidade de tais danos.

Informações relacionadas

Exemplos de consulta OData da API do Microsoft Cloud for Sustainability
Metodologia de cálculo da API do Microsoft Cloud for Sustainability
API do Microsoft Cloud for Sustainability