Обзор API-интерфейсов Cloud for Sustainability (предварительная версия)

Microsoft Cloud for Sustainability предоставляет API-интерфейсы для доступа к данным о выбросах, связанных с вашим использованием Azure и Microsoft 365.

Точный учет выбросов углерода требует достоверной информации от партнеров, продавцов и поставщиков. API-интерфейсы Cloud for Sustainability обеспечивают прозрачность данных о выбросах углекислого газа, возникающих в результате использования Azure и Microsoft 365. Учет выбросов углекислого газа Microsoft распространяется на все три области выбросов с помощью методологии, проверенной третьей стороной. Он использует последовательный и точный учет выбросов углекислого газа для количественной оценки влияния Azure и Microsoft 365 на воздействие клиентов на окружающую среду.

Подробная информация об этом API-интерфейсе приведена в разделе Справочник по API-интерфейсу Microsoft Cloud for Sustainability. Они включают дополнительную информацию об операциях, параметрах и ответах.

• Начало работы с API-интерфейсами Cloud for Sustainability
• Примеры запросов
• Назначение разрешений
• Управление экземплярами
• Просмотр использования API-интерфейса
• Вопросы и ответы

Начало работы с API-интерфейсами Cloud for Sustainability

Начните работу с API-интерфейсами, выполнив следующие процедуры:

• Ознакомление с поддерживаемыми учетными записями
• Вход в систему и создание экземпляра
• Настройка источников данных и включение API-интерфейсов
• Опробывание API-интерфейсов

Поддерживаемые учетные записи

• Azure: API-интерфейсы Microsoft Cloud for Sustainability для Azure поддерживают учетные записи EA Direct, MCA и MPA с прямым выставлением счетов с Microsoft. Клиенты, приобретающие Azure у поставщика облачных решений (CSP), не поддерживаются и должны работать напрямую со своим CSP, чтобы узнать о своих выбросах из-за использования облака. Устаревшие учетные записи, учетные записи на основе кредитов, регистрации в Китае и учетные записи Azure для государственных учреждений не поддерживаются. Чтобы проверить тип учетной записи, перейдите по ссылке Проверка типа вашей учетной записи.

  Заметка

  Использование преимущества гибридного использования Azure в настоящее время не фиксируется и не отражается в выбросах.

• Microsoft 365 : API-интерфейсы Microsoft Cloud for Sustainability для Microsoft 365 поддерживают подписки для бизнеса, предприятий или образования для Microsoft 365 или Office 365. Национальные/региональные облачные развертывания, включая, помимо прочего, облака Microsoft для правительства США и Office 365, управляемые 21Vianet, не поддерживаются.

Вход в систему и создание экземпляра

Получив доступ к API-интерфейсам Microsoft Cloud for Sustainability от Microsoft, войдите в систему, используя свои учетные данные Azure Microsoft Entra ID.

Вам необходимо создать экземпляр для доступа к API-интерфейсам Microsoft Cloud for Sustainability. Создав экземпляр, вы становитесь администратором этого экземпляра. Администратор экземпляра может добавлять пользователей, группы и приложения в экземпляр.

Посмотрите это видео, чтобы получить обзор использования API-интерфейсов и портала Cloud for Sustainability:

Настройка источников данных и включение API-интерфейсов

1. На вкладке Источники данных переключите соединение в состояние включено, чтобы подключить данные о выбросах Azure или Microsoft 365. Прежде чем использовать API-интерфейсы, убедитесь, что статус указан как Доступен. Это действие включает данные о выбросах, относящиеся ко всем регистрациям или учетным записям выставления счетов, к которым у вас есть доступ. Если у вас нет доступа к каким-либо данным о выбросах, продолжайте использовать только демонстрационные данные.

   Заметка

   Прежде чем данные о выбросах Microsoft 365 станут доступны после включения источника данных, может пройти до 48 часов. Отключение источника данных Microsoft 365 приведет к безвозвратному удалению исторических данных о выбросах Microsoft 365.

   

2. Выберите вкладку Управление API-интерфейсом, затем выберите Включить.

   При включении API-интерфейса создаются первичные и вторичные ключи API, которые ваш экземпляр может использовать в запросах API-интерфейса. Чтобы сгенерировать ключи, выберите . Чтобы скопировать ключи, выберите .

Хотите настроить приложение для вызова API-интерфейса Cloud for Sustainability? Посмотрите эту демонстрацию:

Опробывание API-интерфейсов

На вкладке Управление API выберите Попробовать API, чтобы изучить API-интерфейсы OData и Export. Выполняйте запросы к данным о выбросах в интерактивном режиме, подключив API-интерфейсы OData с малой задержкой к вашим панелям мониторинга. Или выполните собственную массовую обработку, передав данные о выбросах непосредственно в свое хранилище Azure Data Lake Storage с помощью API-интерфейсов экспорта. Портал разработчика откроется на новой вкладке, где вы сможете изучить схемы запросов и ответов, а также выполнять интерактивные запросы к API-интерфейсам Microsoft Cloud for Sustainability.

Опробывание API-интерфейсов OData

1. На левой панели навигации убедитесь, что Группировка по тегу включена, и выберите группировку OData, чтобы просмотреть API-интерфейсы OData Azure и Microsoft 365.

2. Чтобы сделать запрос в реальном времени, выберите Попробовать. Введите все требуемые поля:

   • Авторизация: автоматически заполняемый токен авторизации
   • Ключ подписки: автоматически заполняется ключом API-интерфейса на вкладке Управление API
   • enrollmentId: ваш идентификатор регистрации, также известный как идентификатор учетной записи для выставления счетов. Только Azure. Если у вас нет доступа к регистрации, вы можете изучить API-интерфейс, используя демонстрационные данные, введя в этом поле demodata.
   • InstanceId: находится в URL-адресе портала API-интерфейса Microsoft Cloud for Sustainability
   • tenantId: идентификатор арендатора Microsoft 365.

   

3. Добавьте все необходимые параметры запроса. Прокрутите до нижней части боковой панели и выберите Отправить. Ответ HTTP отображается в нижней части области.

Посмотрите это видео, чтобы узнать больше об API-интерфейсах Cloud for Sustainability с OData:

Опробование API-интерфейсов экспорта

1. На панели навигации слева убедитесь, что Группировка по тегу включена, и выберите группировку Экспорт, чтобы начать экспорт данных о выбросах и использовании в ваше озеро данных. Выберите RunExportJob.

2. Выберите Попробовать. Введите все необходимые поля и выберите Отправить.

   • Авторизация: автоматически заполняемый токен авторизации
   • Ключ подписки: автоматически заполняется ключом API-интерфейса на вкладке Управление API
   • InstanceId: находится в URL-адресе портала API-интерфейса Microsoft Cloud for Sustainability
   • ExportJobType: выберите Azure или Microsoft 365, чтобы назначить источник данных о выбросах и использовании для экспорта.
   • demodata: введите «true», если вы хотите изучить эту функциональность путем экспорта демонстрационных данных.

3. После выбора Отправить прокрутите вниз, чтобы увидеть ответ HTTP. Если вы экспортируете данные Azure, в ответе будут указаны идентификаторы регистрации для экспортированных данных. Если у вас нет доступа к данным Azure или Microsoft 365, эта операция не удастся. Убедитесь, что вы правильно настроили источники данных.

   Первоначально ответ указывает, что задание имеет NotStarted. Задание экспорта занимает 2–3 минуты, и вы можете использовать идентификатор задания jobID для проверки статуса экспорта с помощью API-интерфейса ExportJobStatus. Убедитесь, что задание выполнено успешно. Это будет означать, что экспортированные данные теперь доступны в промежуточном хранилище BLOB-объектов.

   Вы можете использовать LatestExportJob для просмотра информации о вашем последнем задании экспорта.

   Вы можете использовать API-интерфейсы ExportJobs для просмотра информации о ваших исторических экспортах.

4. Используйте API-интерфейсы ExportLocation, чтобы получить URL-адрес SAS. Срок действия URL-адреса SAS составляет один час. Скопируйте URL-адрес SAS, чтобы получить доступ к экспортированным данным из промежуточного хранилища BLOB-объектов.

5. Срок действия данных истекает через 28 дней после запуска задания экспорта, и их необходимо скопировать до истечения срока действия. В противном случае данные удаляются из промежуточного местоположения. Пользователи могут в любое время повторно запустить задание по экспорту, чтобы получить еще один пакет данных со сроком действия 28 дней, включающий самый последний набор данных. Есть несколько способов получить доступ к экспортированным данным.

   1. Обозреватель службы хранилища Azure

      Установите и откройте Обозреватель службы хранилища Azure. Выберите кнопку Открыть диалоговое окно подключения, затем выберите Контейнер или каталог ADLS Gen2. Выберите Подписанный URL-адрес (SAS) и вставьте URL-адрес SAS из шага 4 во входные данные URL-адрес контейнера BLOB-объектов или каталога SAS. Выберите Далее, затем выберите Подключиться. Вам необходимо найти или создать контейнер в новой или существующей учетной записи хранения, которая будет использоваться для хранения экспортированных данных. Скопируйте данные Azure или Microsoft 365 из промежуточного хранилища BLOB-объектов и вставьте их в выбранный контейнер.

   2. Используйте azcopy. Используя URL-адрес SAS из шага 4 и URL-адрес учетной записи хранения, в которой вы храните экспортированные выбросы (целевой URL-адрес), запустите команду azcopy.exe:

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

   3. Скрипт Spark

      Используйте mssparkutils в Microsoft Fabric или Synapse. Вы можете использовать альтернативные библиотеки и среды.

      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)
      

Примеры запросов

Краткий список примеров запросов OData для работы с API-интерфейсами см. в разделе примеры запросов OData.

Назначение разрешений

Доступ к API-интерфейсам Microsoft Cloud for Sustainability ограничен только пользователям вашей организации, которых администратор экземпляра добавляет в приложение. Пользователь может быть отдельным пользователем, группой или приложением. Гостевые учетные данные не поддерживаются. Вы можете назначить три типа ролей:

• Зритель: можно просмотреть все страницы внутри API-интерфейса Microsoft Cloud for Sustainability.
• Участник: может взаимодействовать со всеми страницами на портале API-интерфейса Microsoft Cloud for Sustainability. Невозможно добавить или удалить пользователей.
• Администратор: доступны все разрешения, включая возможность добавлять и удалять пользователей.

Чтобы добавить пользователей, группы или приложения в качестве администратора:

1. Выберите вкладку Разрешения, затем выберите Добавить пользователей.
2. Используйте поле Поиск, чтобы найти пользователя, приложение или группу Microsoft Entra ID, которых вы хотите добавить.
3. Выберите назначение роли, затем выберите Сохранить.

Управление экземплярами

Перейдите к значку , чтобы найти список всех экземпляров, создать экземпляры или удалить экземпляры.

Просмотр использования API

Просмотрите подробную информацию об использовании API-интерфейса в реальном времени.

1. Перейдите на вкладку Управление API-интерфейсом, затем выберите Использование.
2. Выберите интервал времени для просмотра.

Страница Использование API состоит из трех разделов:

• Вызовы API: диаграмма, отображающая агрегированное количество обращений к API в выбранном интервале времени.
• Передача данных: диаграмма, показывающая объем данных, переданных через API в выбранном интервале времени.
• Операции: таблица со строками для каждой доступной операции API и подробностями об использовании операций.

Вопросы и ответы

Как Microsoft рассчитывает выбросы углекислого газа в облаках, предоставляемые API-интерфейсом?

Для получения информации о методологии расчета Microsoft перейдите в раздел Методологии расчета API-интерфейса Microsoft Cloud for Sustainability.

Где я могу узнать больше о написании запросов с помощью OData?

Чтобы узнать больше об OData, перейдите в раздел Обзор параметров запроса.

Где хранятся данные, используемые для создания этого отчета?

Данные хранятся в Соединенных Штатах.

Почему я не могу просмотреть данные о выбросах за предыдущий месяц?

Данные о выбросах за определенный месяц будут доступны на 14-й день после окончания этого месяца (включая нерабочие дни).

Я не могу создать экземпляр. Почему?

Возможно, вы пытаетесь получить доступ к порталу API-интерфейсов Cloud for Sustainability с помощью учетной записи, связанной с другим идентификатором арендатора узла, нежели тот, который был указан в форме регистрации. Такая ситуация может возникнуть, если вы используете гостевую учетную запись. Гостевые учетные данные не поддерживаются. Если вы хотите, чтобы мы подключили еще одного клиента, повторно отправьте форму регистрации.

У меня другой идентификатор клиента для Microsoft 365 и Azure. Могу ли я по-прежнему использовать API-интерфейс Microsoft Cloud for Sustainability?

Вы по-прежнему можете получить доступ к API-интерфейсам, но портал не поддерживает несколько клиентов на один экземпляр. Вам необходимо подключить этих клиентов к API-интерфейсам отдельно.

Как настроить приложение для вызова API-интерфейса Microsoft Cloud for Sustainability?

Хотите настроить приложение для вызова API-интерфейса Cloud for Sustainability? Посмотрите эту демонстрацию:

На портале Azure перейдите к своему Microsoft Entra ID, выберите Регистрации приложений, а затем + Создать регистрацию. На странице создания регистрации укажите имя для регистрации вашего приложения, настройте параметры в соответствии со своими потребностями, а затем выберите Зарегистрировать. Перейдите на страницу Microsoft Entra ID, выберите колонку Корпоративные приложения, установите Тип приложения на Приложения Microsoft и выполнять поиск по имени приложения MCFS SDS. Параметр ApplicationId, который вы передали в команде New-AzADServicePrincipal, необходимой во время подключения, является ApplicationId API-интерфейса Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), с помощью которого вы создали экземпляр (корпоративное приложение) регистрации приложения API-интерфейса Microsoft Cloud for Sustainability в вашем собственном клиенте.

Теперь вы можете перейти на страницу регистрации приложения и выбрать колонку разрешения API. Чтобы добавить разрешение, чтобы регистрация вашего приложения могла вызвать API-интерфейс Microsoft Cloud for Sustainability, выберите + Добавить разрешение, затем параметр API-интерфейсы, которые использует моя организация. Затем найдите ApplicationId API-интерфейса Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), выберите MCFS SDS, затем выберите разрешение App.Emissions.Read колонки Разрешения приложения.

Для этого разрешения типа приложения необходимо получить согласие администратора, выбрав Предоставить согласие администратора для {your-tenant}.

Наконец, посетите домашнюю страницу API-интерфейса Microsoft Cloud for Sustainability, перейдите к колонке Разрешения, затем выберите + Добавить. На появившейся боковой панели выберите Зритель в качестве роли во входных данных пользователя, группы или приложения и приступите к поиску регистрации вашего приложения. Выберите Сохранить.

Я получаю маркер доступа для своего приложения, какой URL-адрес ресурса?

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

Сколько исторических данных доступно?

• Azure: данные об использовании и выбросах охватывают данные за последние пять лет, связанные с регистрацией.
• Microsoft 365 : данные о выбросах охватывают данные за последние 12 месяцев, связанные с подпиской Microsoft 365.

Отказ от ответственности

API-интерфейс Microsoft Cloud for Sustainability (предварительная версия) основан на отраслевых стандартах расчета выбросов углекислого газа на серверах. Он предоставляет общие оценки, помогающие организациям получить представление о выбросах углекислого газа в ИТ-инфраструктуре, связанных с использованием облачных сервисов Azure. Выводы, интерпретации и заключения, представленные API-интерфейсом Microsoft Cloud for Sustainability (предварительная версия), включая расчеты, не являются конкретными советами или рекомендациями. Приведенная информация и мнения могут быть изменены без предварительного уведомления. API-интерфейс Microsoft Cloud for Sustainability (предварительная версия) предоставляется «как есть», без каких-либо заявлений или гарантий любого рода, явных или подразумеваемых, включая, помимо прочего, любые заявления или одобрения относительно использования, результатов или производительности API-интерфейса Microsoft Cloud for Sustainability (предварительная версия), его пригодности, точности, надежности или правильности. Весь риск, связанный с использованием API-интерфейса Microsoft Cloud for Sustainability (предварительная версия), вы принимаете на себя. Microsoft не несет ответственности за использование API-интерфейса Microsoft Cloud for Sustainability (предварительная версия). Ни при каких обстоятельствах корпорация Microsoft не будет нести ответственность за другие прямые или косвенные убытки, включая любую упущенную выгоду, потерянные сбережения или любые случайные или косвенные убытки, возникшие из-за любых дефектов или использования или невозможности использования API-интерфейсов Microsoft Cloud for Sustainability (предварительная версия), даже если корпорация Microsoft была уведомлена о возможности таких убытков.

Дополнительные сведения

Примеры запросов API-интерфейса OData Microsoft Cloud for Sustainability
Методология расчета API-интерфейса Microsoft Cloud for Sustainability
API-интерфейс Microsoft Cloud for Sustainability