Ler em inglês

Partilhar via


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

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: Microsoft Cloud for Sustainability APIs para Azure suportam contas EA Direct, MCA e MPA com Relações de faturamento direto com 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

    Azure O uso do Benefício Híbrido não é atualmente capturado ou refletido nas emissões.

  • Microsoft 365: Microsoft Cloud for Sustainability APIs para Microsoft 365 subscrições empresariais, empresariais ou educativas de suporte para 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, é necessária uma das seguintes funções: administrador do Exchange, administrador do Skype para Empresas, administrador do SharePoint, Leitor global, 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 preenchido automaticamente
    • Chave de assinatura: preenchida automaticamente com a chave da API na guia Gerenciamento de API
    • enrollmentId: seu ID de inscrição, também conhecido como ID da conta de cobrança. 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: Encontrado na URL do portal Microsoft Cloud for Sustainability da API
    • tenantId: Microsoft 365 ID do locatário.

    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 preenchido automaticamente
    • Chave de assinatura: preenchida automaticamente com a chave da API na guia Gerenciamento de API
    • instanceId: Encontrado na URL do portal Microsoft Cloud for Sustainability da API
    • exportJobType: Selecione Azure ou Microsoft 365 para designar o origem de dados de emissões e dados de uso a serem exportados.
    • demodata: insira "true" se você quiser explorar essa 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.

      Python
      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 visualizar todas as páginas dentro da Microsoft Cloud for Sustainability API.
  • contribuinte: Pode interagir com todas as páginas no portal da Microsoft Cloud for Sustainability API. Não pode adicionar ou remover utilizadores.
  • Admin: Todas as permissões disponíveis, incluindo a capacidade de adicionar ou remover usuários.

Nota

Os contribuidores e os admins não podem desativar nem ativar a origem de dados do Microsoft 365 a menos que sejam administrador do Exchange, administrador do Skype para Empresas, administrador do 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 de API: um gráfico que visualiza o número agregado de chamadas para a API na período de tempo selecionada.
  • Transferência de dados: um gráfico que mostra a quantidade de dados que foram transferidos através da API no período de tempo selecionado.
  • Operações: uma tabela com linhas para cada operação de API disponível e detalhes sobre o uso 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 você passou no comando New-AzADServicePrincipal necessário durante a integração é o ApplicationId da API ( Microsoft Cloud for Sustainability ) com a00001111-aaaa-2222-bbbb-3333cccc4444qual você criou uma instância (aplicativo empresarial) do Microsoft Cloud for Sustainability registro do aplicativo de API em seu próprio locatário.

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 o Microsoft Cloud for Sustainability ApplicationId da API (00001111-aaaa-2222-bbbb-3333cccc4444), selecione MCFS SDS e, em seguida, selecione a permissão App.Emissions.Read da folha Application permissions .

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?

00001111-aaaa-2222-bbbb-3333cccc4444/.default

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

  • Azure: Os dados de uso e emissões abrangem os últimos cinco anos de dados associados à inscrição.
  • Microsoft 365: Os dados relativos às emissões abrangem os últimos 12 meses de dados associados à Microsoft 365 subscrição.

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.

Microsoft Cloud for Sustainability API OData exemplos
Microsoft Cloud for Sustainability de consulta API metodologia
Microsoft Cloud for Sustainability de cálculo API