Visão geral da API do Cloud for Sustainability (versão preliminar)
Microsoft Cloud for Sustainability - Avaliação gratuita
Importante
Algumas ou todas estas funcionalidades estão disponíveis como parte de uma versão preliminar. O conteúdo e a funcionalidade estão sujeitos a alterações.
O Microsoft Cloud for Sustainability fornece APIs para acessar dados de emissões relacionados ao seu uso do Azure e do Microsoft 365.
A contagem de carbono precisa requer boas informações de parceiros e fornecedores. As APIs do Cloud for Sustainability oferecem transparência sobre as emissões de carbono geradas pelo uso do Azure e do Microsoft 365. A contagem de carbono da Microsoft se estende por todos os três escopos de emissões, com uma metodologia validada por terceiros. Ela usa uma contagem de carbono consistente e precisa para quantificar o efeito do Azure e do Microsoft 365 na pegada ambiental dos clientes.
Os detalhes da API estão listados na Referência de API do Microsoft Cloud for Sustainability. Eles incluem informações adicionais sobre operações, parâmetros e respostas.
- Introdução às APIs do Cloud for Sustainability
- Consultas de exemplo
- Atribuir permissões
- Gerenciar instâncias
- Exibir o uso da API
- Perguntas frequentes
Importante
A API do Microsoft Cloud for Sustainability está atualmente em versão preliminar e está sujeita a alterações. Seus valores históricos de emissões também podem ser atualizados à medida que a Microsoft faz melhorias na precisão e integridade dos dados. Esta versão preliminar não se destina a fins de conformidade legal, marketing ou geração de relatórios.
Introdução às APIs do Cloud for Sustainability
Observação
Se a sua organização deseja obter acesso à API do Microsoft Cloud for Sustainability (versão preliminar), envie este formulário de inscrição.
Comece a usar as APIs com os seguintes procedimentos:
- Revisar as contas com suporte
- Entrar e criar uma instância
- Configure as fontes de dados e habilitar as APIs
- Experimentar as APIs
Contas com suporte
Azure: as APIs do Microsoft Cloud for Sustainability para Azure oferecem suporte a contas de EA Direct, MCA e MPA com relacionamentos de cobrança direta com a Microsoft. Os clientes que compram o Azure de um Provedor de Soluções de Nuvem (CSP) não têm suporte e devem trabalhar diretamente com seu CSP para saber mais sobre suas emissões de nuvem. Não há suporte para contas herdadas, contas baseadas em créditos, registros da China e contas do Azure Governamental. Para verificar seu tipo de conta, acesse Verifique o tipo da sua conta.
Observação
No momento, o uso do Benefício Híbrido do Azure não está capturado nem é refletido nas emissões.
Microsoft 365: as APIs do Microsoft Cloud for Sustainability para Microsoft 365 oferecem suporte a assinaturas comerciais, corporativas ou educacionais para Microsoft 365 ou Office 365. Não há suporte às implantações nacionais/regionais de nuvem, incluindo, entre outros, nuvens do Governo dos EUA da Microsoft e o Office 365 operado pela 21Vianet.
Entrar e criar uma instância
Depois de receber acesso às APIs do Microsoft Cloud for Sustainability da Microsoft, entre com suas credenciais do Microsoft Entra ID do Azure.
Você deve criar uma instância para acessar as APIs do Microsoft Cloud for Sustainability. Ao criar a instância, você se torna o administrador dela. O administrador da instância pode adicionar usuários, grupos e aplicativos a ela.
Assista a este vídeo para obter uma visão geral do uso das APIs e do portal do Cloud for Sustainability:
Configurar as fontes de dados e habilitar as APIs
Importante
Para habilitar com êxito o acesso aos dados da sua organização, esta etapa deve ser executada pelo administrador relevante. Para contas do Azure MCA, é necessário um administrador de conta de cobrança com função de leitor, colaborador ou proprietário da conta de cobrança. Para contas EA do Azure, é necessário um administrador corporativo ou administrador corporativo - somente leitura. Verifique sua função no portal do Azure. Para o Microsoft 365, uma das seguintes funções é necessária: administrador global, administrador do Exchange, administrador do Skype for Business, administrador do SharePoint, leitor global, leitor de relatórios. Os administradores do Azure e do Microsoft 365 podem criar instâncias ou ser adicionados a instâncias para habilitar fontes de dados e habilitar a API. Se não tiver uma função de administrador necessária para habilitar os dados, você poderá explorar a API usando somente os dados de demonstração.
Na guia Fontes de Dados, ative a conexão para conectar os dados de emissões do Azure ou do Microsoft 365. Verifique se o status está listado como Disponível antes de usar as APIs. Esta ação ativa os dados de emissão relacionados a todas as inscrições ou contas de cobrança às quais você tem acesso. Se você não tiver acesso a dados de emissões, prossiga apenas com os dados de demonstração.
Observação
Pode levar até 48 horas para que os dados de emissões do Microsoft 365 fiquem disponíveis após a habilitação da fonte de dados. A desabilitação da fonte de dados do Microsoft 365 excluirá permanentemente os dados de emissões históricos do Microsoft 365.
Selecione a guia Gerenciamento de API e, em seguida, selecione Habilitar.
Habilitar API gera chaves de API primárias e secundárias para sua instância usar em solicitações de API. Para regenerar as chaves, selecione
. Para copiar as chaves, selecione 
.
Tem interesse em configurar um aplicativo para chamar a API do Cloud for Sustainability? Assista a esta demonstração:
Experimentar as APIs
Na guia Gerenciamento de API, selecione Testar API para explorar o OData e APIs de Exportação. Consulte interativamente seus dados de emissões conectando APIs do OData de baixa latência aos seus painéis. Ou faça seu próprio processamento em massa transferindo dados de emissões diretamente para o Azure Data Lake Storage usando APIs de Exportação. Um portal do desenvolvedor é aberto em uma nova guia onde você pode explorar os esquemas de solicitação e resposta e fazer solicitações ao vivo em APIs do Microsoft Cloud for Sustainability.
Testar APIs do OData
Na navegação à esquerda, certifique-se de que Agrupar por tag esteja ativado e selecione o agrupamento OData para revisar APIs do Azure e do OData do Microsoft 365.
Para fazer uma solicitação dinâmica, selecione Experimentar. Inserir todos os campos obrigatórios
- Autorização: token de autorização preenchido automaticamente
- Chave de assinatura: preenchida automaticamente com a chave de API na guia Gerenciamento de API
- enrollmentId: sua ID de inscrição, também conhecida como ID da conta de cobrança. Somente Azure. Se você não tiver acesso a uma inscrição, poderá explorar a API usando dados de demonstração inserindo demodata neste campo.
- instanceId: encontrada na URL do portal da API do Microsoft Cloud for Sustainability
- tenantId: ID do locatário do Microsoft 365.
Adicione todos os parâmetros de consulta necessários. Role até a parte inferior do painel lateral e selecione Enviar. A resposta HTTP será exibida na parte inferior do painel.
Assista a este vídeo para saber mais sobre as APIs do Cloud for Sustainability com OData:
Testar APIs de Exportação
Na navegação à esquerda, certifique-se de que Agrupar por tag esteja ativado e selecione o agrupamento Exportar para começar a exportar emissões e uso dados para o seu data lake. Selecione RunExportJob.
Selecione Experimentar. Insira todos os campos obrigatórios e selecione Enviar.
- Autorização: token de autorização preenchido automaticamente
- Chave de assinatura: preenchida automaticamente com a chave de API na guia Gerenciamento de API
- instanceId: encontrada na URL do portal da API do Microsoft Cloud for Sustainability
- exportJobType: selecione Azure ou Microsoft 365 para designar a fonte de dados para emissões e dados de uso para exportação.
- demodata: digite "true" se desejar explorar essa funcionalidade, exportando dados de demonstração.
Depois de selecionar Enviar, role para baixo para ver a resposta HTTP. Se você estiver exportando dados do Azure, a resposta listará as IDs de inscrição para os dados exportados. Se você não tiver acesso a dados do Azure ou do Microsoft 365, esta operação não terá êxito. Verifique se você configurou corretamente suas fontes de dados.
Inicialmente, a resposta indica que o trabalho tem NotStarted. O trabalho de exportação leva de 2 a 3 minutos para ser concluído e você pode usar o jobID para verificar o status da exportação usando a API ExportJobStatus. Verifique se o trabalho teve êxito, o que indica que os dados exportados agora estão disponíveis no armazenamento de blob de preparo.
Você pode usar LatestExportJob para revisar informações sobre seu último trabalho de exportação.
Você pode usar a API ExportJobs para revisar informações sobre o histórico de exportações.
Use a API ExportLocation para obter a URL SAS. A URL de SAS expirará após uma hora. Copie a URL de SAS para acessar os dados exportados do armazenamento de blob de preparo.
Os dados são definidos para expirar 28 dias após a execução do trabalho de exportação e devem ser copiados antes da expiração. Caso contrário, os dados serão excluídos do local de preparo. Os usuários podem reexecutar um trabalho de exportação a qualquer momento para obter outro lote de dados com validade de 28 dias e incluindo o conjunto de dados mais recente. Existem algumas maneiras de acessar os dados exportados.
Gerenciador de Armazenamento do Azure
Instale e abra o Gerenciador de Armazenamento do Azure. Selecione o botão Abrir Caixa de Diálogo de Conexão e, depois, selecione Contêiner ou diretório ADLS Gen2. Selecione URL de assinatura de acesso compartilhado (SAS) e cole a URL SAS da etapa 4 na entrada URL SAS de contêiner ou diretório Blob. Selecione Avançar e, depois, Conectar. Você precisa localizar ou criar um contêiner em uma conta de armazenamento nova ou existente a ser usada para armazenar esses dados exportados. Copie os dados do Azure ou do Microsoft 365 do armazenamento de blob de preparo e cole no contêiner de sua preferência.
Use o azcopy. Usando a URL SAS da etapa 4 e a URL da conta de armazenamento onde você está armazenando emissões exportadas (URL de destino), execute o comando azcopy.exe:
azcopy loginazcopy list <SAS URL>azcopy cp <SAS URL> <destination URL>
Script de Spark
Use mssparkutils no Microsoft Fabric ou no Synapse. Você pode optar por usar 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 ver uma breve lista de consultas OData de exemplo para trabalhar com as APIs, acesse Exemplos de consulta OData.
Atribuir permissões
O acesso às APIs do Microsoft Cloud for Sustainability é restrito a usuários em sua organização que um administrador de uma instância adiciona ao aplicativo. Um usuário pode ser um único usuário, um grupo ou um aplicativo. Não há suporte para contas de convidado. Existem três tipos de funções que podem ser atribuídas:
- Visualizador: pode visualizar todas as páginas na API do Microsoft Cloud for Sustainability.
- Colaborador: pode interagir com todas as páginas no portal da API do Microsoft Cloud for Sustainability. Não pode adicionar ou remover usuários.
- Admin: todas as permissões disponíveis, incluindo a possibilidade de adicionar ou remover usuários.
Observação
Colaboradores e administradores não podem desabilitar ou habilitar a fonte de dados do Microsoft 365, a menos que sejam administradores globais, administradores do Exchange, administradores do Skype for Business, administradores do SharePoint, leitores globais ou leitores de relatórios.
Para adicionar usuários, grupos ou aplicativos como administrador:
- Selecione a guia Permissões e, em seguida, selecione Adicionar Usuários.
- Use o campo Pesquisar para encontrar o usuário, o aplicativo ou o grupo do Microsoft Entra ID que você deseja adicionar.
- Escolha uma atribuição de função e selecione Salvar.
Gerenciar instâncias
Navegue até o ícone da instância 
para encontrar uma lista de todas as instâncias, criar ou remover instâncias.
Exibir o uso da API
Exibir detalhes sobre o uso da API em tempo real.
- Navegue até a guia Gerenciamento de API e selecione Uso.
- Selecione um período a ser exibido.
A página Uso da API contém três seções:
- Chamadas de API: um gráfico que visualiza o número agregado de chamadas à API no período selecionado.
- Transferência de dados: um gráfico que mostra o volume de dados que foram transferidos por meio da API no período selecionado.
- Operações: uma tabela com linhas para cada operação de API disponível e detalhes sobre o uso das operações.
Perguntas frequentes
Como a Microsoft calcula as emissões de carbono da nuvem disponibilizadas pela API?
Para obter mais informações sobre a metodologia de cálculo da Microsoft, acesse Metodologia de cálculo da API do Microsoft Cloud for Sustainability.
Onde posso saber mais sobre como escrever consultas com OData?
Para saber mais sobre o OData, acesse Visão geral das opções de consulta.
Onde são armazenados os dados usados para produzir este relatório?
O dados são armazenados nos Estados Unidos.
Por que não consigo ver os dados de emissões do mês anterior?
Os dados de emissão de determinado mês estarão disponíveis até o 14º dia após o final desse mês (incluindo dias não úteis).
Não consigo criar uma instância. Por quê?
Você pode estar tentando acessar o portal de API do Cloud for Sustainability com uma conta associada a um ID de locatário de um host diferente do fornecido no formulário de integração. Isso pode ocorrer quando você usa uma conta de convidado. Não há suporte para contas de convidado. Se você desejar que integremos outro locatário, reenvie o formulário de integração.
Tenho uma ID de locatário diferente para Microsoft 365 e Azure. Ainda posso usar a API do Microsoft Cloud for Sustainability?
Você ainda pode acessar as APIs, mas o portal não dá suporte a vários locatários por instância. Você deve integrar esses locatários às APIs separadamente.
Como configurar um aplicativo para chamar a API do Microsoft Cloud for Sustainability?
Tem interesse em configurar um aplicativo para chamar a API do Cloud for Sustainability? Assista a esta demonstração:
No portal do Azure, acesse seu Microsoft Entra ID, selecione Registros de aplicativo e, em seguida, + Novo registro. Na nova página de registro, dê um nome ao registro do aplicativo, personalize as opções de acordo com suas necessidades e selecione Registrar. Acesse a página Microsoft Entra ID, selecione a folha Aplicativos empresariais, defina Tipo de aplicativo como Aplicativos da Microsoft e pesquise pelo nome do aplicativo MCFS SDS. O parâmetro ApplicationId que você passou no comando New-AzADServicePrincipal necessário durante a integração é o ApplicationId da API do Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9) com o qual você criou uma instância (aplicativo corporativo) do registro de aplicativo de API do Microsoft Cloud for Sustainability em seu próprio locatário.
Com isso definido, agora você pode acessar a página de registro do aplicativo e selecionar a folha Permissões da API. Para adicionar permissão ao registro do seu aplicativo para poder chamar a API do Microsoft Cloud for Sustainability, selecione + Adicionar uma permissão, seguido da opção APIs que minha organização usa. Depois, procure o ApplicationId da API do Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), selecione MCFS SDS e, depois, selecione a permissão App.Emissions.Read da folha Permissões do aplicativo.
Essa permissão de tipo de aplicativo precisa obter o consentimento do administrador selecionando Conceder consentimento de administrador para {your-tenant}.
Por último, visite a home page da API do Microsoft Cloud for Sustainability, navegue até a folha Permissões e, depois, selecione + Adicionar. No painel lateral que aparece, escolha Visualizador como a Função na entrada Usuário, Grupo ou Aplicativo e prossiga para procurar o registro do seu aplicativo. Selecione Salvar.
Estou obtendo um token de acesso para meu aplicativo. Qual é a URL do recurso?
c3163bf1-092f-436b-b260-7ade5973e5b9/.default
Que volume de dados históricos está disponível?
- Azure : os dados de uso e emissões cobrem os últimos cinco anos de dados associados à inscrição.
- Microsoft 365: os dados de emissões cobrem os últimos 12 meses de dados associados à assinatura do Microsoft 365.
Aviso de isenção de responsabilidade
A API (versão preliminar) do Microsoft Cloud for Sustainability se baseia em padrões do setor para 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 associadas ao uso dos serviços de nuvem do Azure. As descobertas, interpretações e conclusões apresentadas com a API (versão preliminar) do Microsoft Cloud for Sustainability, incluindo os cálculos, não são orientações ou recomendações específicas. As informações e opiniões expressas podem mudar sem aviso prévio. A API (versão preliminar) do Microsoft Cloud for Sustainability é fornecida como está, sem representação ou garantia de qualquer tipo, expressa ou implícita, incluindo, sem limitação, quaisquer representações ou endossos relacionados ao uso, resultados ou desempenho da API (versão preliminar) do Microsoft Cloud for Sustainability, sua adequação, precisão, confiabilidade ou correção. Você assume o total risco quanto ao uso da API (versão preliminar) do Microsoft Cloud for Sustainability. A Microsoft não assume responsabilidade pelo uso da API (versão preliminar) do Microsoft Cloud for Sustainability. Em nenhuma hipótese, a Microsoft será responsável por danos diretos ou indiretos adicionais, incluindo lucros cessantes, economias perdidas ou danos incidentais ou consequenciais decorrentes de defeitos ou do uso ou da incapacidade de usar a API (versão preliminar) do Microsoft Cloud for Sustainability, mesmo que a Microsoft tenha sido avisada da possibilidade de tais danos.
Ver também
Exemplos de consulta OData da API do Microsoft Cloud for SustainabilityMetodologia de cálculo da API do Microsoft Cloud for SustainabilityAPI do Microsoft Cloud for Sustainability
