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

  • Artigo

Cimeira Técnica do Microsoft Cloud for Sustainability, maio de 2024

Importante

Algumas ou todas estas funcionalidades estão disponíveis como parte de uma versão de pré-visualização. O conteúdo e a funcionalidade estão sujeitos a alterações.

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.

Importante

A API do Microsoft Cloud for Sustainability está atualmente em pré-visualização e está sujeita a alterações. Os números das emissões históricas também podem ser atualizadas à medida que a Microsoft faz melhorias na precisão e integridade dos dados. Esta pré-visualização não se destina a fins de conformidade legal, marketing ou comunicação.

Introdução às API do Cloud for Sustainability

Nota

Se a sua organização quiser obter acesso à API do Microsoft Cloud for Sustainability (pré-visualização), submeta este formulário de inscrição.

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

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 API do Microsoft Cloud for Sustainability para o Microsoft 365 suportam subscrições business, enterprise ou education para o Microsoft 365 ou 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

Importante

Para ativar o acesso com êxito aos dados da sua organização, este passo tem de ser e executado pelo administrador relevante. Para contas Azure MCA, é necessário um administrador de conta de faturação com uma função de leitor, contribuidor ou proprietário de conta de faturação. Para contas Azure EA, é necessário um administrador de empresa ou administrador de empresa só de leitura. Verifique a sua função no portal do Azure. Para o Microsoft 365, é obrigatória uma das seguintes funções: Administração global, administrador Exchange, administrador Skype para Empresas, admin SharePoint, Leitor global e Leitor de relatórios. Os administradores de Azure e do Microsoft 365 podem criar instâncias ou ser adicionados a instâncias para ativar origens de dados e ativar as API. Se não tiver uma função de administrador obrigatória para ativar os dados, pode explorar a API usando apenas dados de demonstração.

  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.

    Origem de dados.

  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 Ícone de atualização.. Para copiar as chaves, selecione Copie o ícone..

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 de inquilino do Microsoft 365.

    Página Experimentar.

  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 teve ê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 da SAS expirará ao fim de duas horas. 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 poderão 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. Podem ser atribuídos três tipos de funções:

  • 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.

Nota

Os contribuidores e administradores podem desativar ou ativar a origem de dados do Microsoft 365, a menos que sejam Administrador global, Administrador Exchange, administrador Skype para Empresas, administrador SharePoint, Leitor global ou Leitor de relatórios.

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 Í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 e fornece estimativas gerais para ajudar as organizações a obter informações sobre as emissões de carbono da infraestrutura de TI associada à utilização dos 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 poderão 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 danos adicionais 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 utilizar a API do Microsoft Cloud for Sustainability (pré-visualização), mesmo que a Microsoft tenha sido informada da possibilidade de tais danos.

Consulte também

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