Přehled rozhraní API Cloud for Sustainability (Preview)

  • Článek

Technický summit Microsoft Cloud for Sustainability v květnu 2024

Důležité

Některé nebo všechny tyto funkce jsou k dispozici jako součást vydání verze Preview. Obsah a funkce se mohou změnit.

Microsoft Cloud for Sustainability poskytuje rozhraní API pro přístup k datům emisí souvisejících s vaším používáním Azure a Microsoft 365.

Přesné uhlíkové účetnictví vyžaduje dobré informace od partnerů, prodejců a dodavatelů. Rozhraní API Cloud for Sustainability vám poskytuje transparentnost ohledně emisí uhlíku generovaných vaším používáním Azure a Microsoft 365. Účtování uhlíku společnosti Microsoft se vztahuje na všechny tři oblasti emisí s metodikou ověřenou třetí stranou. Používá konzistentní a přesné uhlíkové účtování ke kvantifikaci dopadu služeb Azure a Microsoft 365 na ekologickou stopu zákazníků.

Podrobnosti o rozhraní API jsou uvedeny v části Referenční informace o rozhraní API Microsoft Cloud for Sustainability. Obsahují další informace o operacích, parametrech a odpovědích.

Důležité

Rozhraní Microsoft Cloud for Sustainability API je aktuálně ve verzi Preview a může se změnit. Vaše historické údaje o emisích mohou být také aktualizovány, protože společnost Microsoft vylepšuje přesnost a úplnost dat. Tato funkce Preview není určena pro účely souladu s právními předpisy, marketingové účely nebo účely podávání zpráv.

Začínáme s rozhraním API Cloud for Sustainability

Poznámka

Pokud by vaše organizace chtěla získat přístup k rozhraní API Microsoft Cloud for Sustainability (Preview), odešlete tento registrační formulář.

Začněte s rozhraními API pomocí následujících postupů:

Podporované účty

  • Azure: Rozhraní API Microsoft Cloud for Sustainability pro Azure podporují účty EA Direct, MCA a MPA s přímými fakturačními vztahy se společností Microsoft. Zákazníci, kteří si kupují Azure od poskytovatele cloudových řešení (CSP), nejsou podporováni a musí spolupracovat přímo se svým poskytovatelem služeb, aby se dozvěděli o svých cloudových emisích. Starší účty, účty založené na kreditech, registrace v Číně a účty Azure Government nejsou podporovány. Chcete-li zkontrolovat typ účtu, přejděte na Zkontrolovat typ účtu.

    Poznámka:

    Používání Zvýhodněného hybridního využití Azure není aktuálně zachyceno ani reflektováno v emisích.

  • Microsoft 365: Microsoft Cloud for Sustainability Rozhraní API pro Microsoft 365 podporují obchodní, podniková nebo vzdělávací předplatná pro Microsoft 365 nebo Office 365. Národní/regionální nasazení cloudu, včetně, ale nejen, cloudů společnosti Microsoft pro státní úřady USA a Office 365 provozovaných společností 21Vianet, nejsou podporována.

Přihlášení a vytvoření instance

Jakmile získáte přístup k rozhraním API Microsoft Cloud for Sustainability od Microsoftu, přihlaste se pomocí svých přihlašovacích údajů Azure Microsoft Entra ID.

Pro přístup k rozhraní API Microsoft Cloud for Sustainability musíte vytvořit instanci. Vytvořením instance se stanete správcem této instance. Administrátor instance může přidávat uživatele, skupiny a aplikace do instance.

Podívejte se na toto video s přehledem používání rozhraní API a portálu Cloud for Sustainability:

Konfigurace zdroje dat a zapnutí rozhraní API

Důležité

Pro úspěšné umožnění přístupu k datům vaší organizace musí tento krok provést příslušný správce. Pro účty Azure MCA je vyžadován správce fakturačního účtu s rolí řtenář, přispěvatel, nebo vlastník fakturačního účtu. Pro účty Azure EA je vyžadován podnikový správce nebo podnikový správce – pouze pro čtení. Svou roli zjistíte na portálu Azure Portal. Pro Microsoft 365 je vyžadována jedna z následujících rolí: globální správce, správce Exchange, správce Skype pro firmy, správce SharePoint, globální čtenář, čtenář sestav. Správci Azure a Microsoft 365 mohou vytvářet instance nebo být přidáni k instancím, aby aktivovali zdroje dat a rozhraní API. Pokud nemáte požadovanou roli správci k aktivaci dat, můžete rozhraní API prozkoumat pouze pomocí ukázkových dat.

  1. Na kartě Zdroje datzapněte připojení pro připojení dat emisí Azure nebo Microsoft 365. Před použitím rozhraní API se ujistěte, že je stav uveden jako Dostupné. Tato akce aktivuje údaje o emisích související se všemi registracemi nebo fakturačními účty, ke kterým máte přístup. Pokud nemáte přístup k žádným emisním datům, pokračujte pouze s ukázkovými daty.

    Poznámka:

    Po zapnutí zdroje dat může trvat až 48 hodin, než budou údaje o emisích Microsoft 365 k dispozici. Deaktivace zdroje dat Microsoft 365 trvale odstaní historické údaje o emisích Microsoft 365.

    Zdroje dat.

  2. Vyberte kartu API Management a potom vyberte Zapnout.

    Zapnutí rozhraní API vygeneruje primární a sekundární klíče rozhraní API, které bude vaše instance používat v požadavcích rozhraní API. Pro opětovné vygenerování klíčů vyberte Ikona Aktualizovat.. Ke kopírování klíčů vyberte Ikona kopírování..

Máte zájem o konfiguraci aplikace pro volání rozhraní API Cloud for Sustainability? Podívejte se na tuto ukázku:

Vyzkoušejte rozhraní API

Na kartě Správa rozhraní API vyberte Vyzkoušet rozhraní API a prozkoumejte rozhraní OData a rozhraní API pro export. Interaktivně se dotazujte na svá emisní data připojením rozhraní API OData s nízkou latencí k vašim řídicím panelům. Nebo proveďte vlastní hromadné zpracování přenosem údajů o emisích přímo do vašeho Azure Data Lake Storage pomocí rozhraní API pro export. Na nové kartě se otevře vývojářský portál, kde můžete prozkoumat schémata požadavků a odpovědí a zadávat živé požadavky proti rozhraním API Microsoft Cloud for Sustainability.

Vyzkoušení rozhraní API OData

  1. V levé navigační nabídce se ujistěte, že je zapnuto Seskupit podle značky a vyberte seskupení OData, abyste si prohlédli rozhraní API Azure a Microsoft 365 OData.

  2. Chcete-li odeslat živý požadavek, vyberte Vyzkoušet. Zadejte všechna požadovaná pole:

    • Autorizace: Automaticky vyplněný autorizační token
    • Klíč předplatného: Automaticky se vyplní klíčem rozhraní API z karty API Management
    • enrollmentId: ID prováděcí smlouvy, označované také jako ID fakturačního účtu. Pouze Azure. Pokud nemáte přístup k zápisu, můžete prozkoumat rozhraní API pomocí ukázkových dat zadáním demodata do tohoto pole.
    • instanceId: Nachází se v adrese URL portálu rozhraní API Microsoft Cloud for Sustainability
    • tenantId: ID tenanta Microsoft 365.

    Stránka Vyzkoušet.

  3. Přidejte všechny potřebné parametry dotazu. Přejděte do dolní části postranního panelu a vyberte Odeslat. Odpověď HTTP se zobrazí v dolní části podokna.

Podívejte se na toto video, kde se dozvíte více o rozhraní API Cloud for Sustainability s OData:

Vyzkoušení rozhraní API pro export

  1. Na levé navigaci zajistěte, že je zapnuté Seskupit podle značky, a vyberte seskupení Export, abyste mohli začít exportovat údaje o emisích a využití do vašeho datového jezera. Vyberte RunExportJob.

  2. Vyberte Vyzkoušet. Zadejte všechna požadovaná pole a vyberte Odeslat.

    • Autorizace: Automaticky vyplněný autorizační token
    • Klíč předplatného: Automaticky se vyplní klíčem rozhraní API z karty API Management
    • instanceId: Nachází se v adrese URL portálu rozhraní API Microsoft Cloud for Sustainability
    • exportJobType: Vyberte Azure nebo Microsoft 365 k určení zdroje dat pro údaje o emisích a využití k exportu.
    • demodata: Pokud chcete tuto funkci prozkoumat exportováním ukázkových dat, zadejte „true“.

  3. Poté, co vyberete Odeslat, přejděte dolů a podívejte se na odpověď HTTP. Pokud exportujete data Azure, v odpovědi jsou uvedena ID registrace pro exportovaná data. Pokud nemáte přístup k datům Azure nebo Microsoft 365, tato operace se nezdaří. Ujistěte se, že máte správně nakonfigurované zdroje dat.

    Zpočátku odpověď označuje, že úloha NotStarted (nezačala). Dokončení úlohy exportu trvá 2–3 minuty a pomocí ID úlohy můžete zkontrolovat stav exportu pomocí rozhraní API ExportJobStatus. Ujistěte se, že úloha byla úspěšná, což znamená, že exportovaná data jsou nyní k dispozici v úložišti přípravného objektu blob.

    Můžete použít LatestExportJob ke kontrole informací týkajících se vaší poslední exportní úlohy.

    Můžete použít rozhraní API ExportJobs ke kontrole informací týkajících se historických exportů.

  4. Použijte rozhraní API ExportLocation pro získání adresy URL SAS. Platnost adresy URL SAS vyprší po dvou hodinách. Zkopírujte adresu URL SAS pro přístup k exportovaným datům z úložiště objektů BLOB fázování.

  5. Platnost dat je nastavena tak, aby vypršela 28 dní po spuštění úlohy exportu a je třeba je před vypršením platnosti zkopírovat. V opačném případě budou data z místa uložení odstraněna. Uživatelé mohou exportní úlohu kdykoli znovu spustit, aby získali další dávku dat s vypršením 28 dnů a včetně nejnovější datová sada. Existuje několik způsobů, jak získat přístup k exportovaným datům.

    1. Azure Storage Explorer

      Nainstalujte a otevřete Průzkumník služby Azure Storage. Vyberte tlačítko Otevřít dialogové okno připojení a poté vyberte kontejner nebo adresář ADLS Gen2. Vyberte Adresa URL sdíleného přístupového podpisu (SAS) a vložte adresu URL SAS z kroku 4 do zadání Adresa URL SAS kontejneru nebo adresáře objektu blob. Zvolte Další a pak vyberte Připojit. Musíte najít nebo vytvořit kontejner v novém nebo existujícím účtu úložiště, který chcete použít k ukládání těchto exportovaných dat. Zkopírujte data Azure nebo Microsoft 365 z úložiště objektů blob fázování a vložte je do kontejneru podle svého výběru.

    2. Použijte azcopy. Pomocí adresy URL SAS z kroku 4 a adresy URL účtu úložiště, kam ukládáte exportované emise (cílová adresa URL), spusťte příkaz azcopy.exe:

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

    3. Skript Spark

      Použijte mssparkutils v Microsoft Fabric nebo Synapse. Můžete si vybrat použití alternativních knihoven a prostředí.

      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)

Vzorové dotazy

Krátký seznam vzorových dotazů OData pro práci s rozhraními API najdete v části Příklady dotazů OData.

Přiřazení uživatelských oprávnění

Přístup k rozhraním API Microsoft Cloud for Sustainability je omezen na uživatele ve vaší organizaci, které do aplikace přidá správce instance. Uživatelem může být jeden uživatel, skupina nebo aplikace. Účty hostů nejsou podporovány. Existují tři typy rolí, které lze přiřadit:

  • Prohlížeč: Může zobrazit všechny stránky v rámci rozhraní API Microsoft Cloud for Sustainability.
  • Přispěvatel: Může komunikovat se všemi stránkami na portálu rozhraní API Microsoft Cloud for Sustainability. Nemůže přidávat ani odebírat uživatele.
  • Správce: Všechna dostupná oprávnění, včetně možnosti přidávat nebo odebírat uživatele.

Poznámka:

Přispěvatelé a správci nemohou deaktivovat ani zapnout zdroj dat Microsoft 365, pokud nejsou globálním správcem, správcem Exchange, správcem Skype pro firmy, správcem SharePoint, globálním čtenářem nebo čtenářem sestavy.

Chcete-li přidat uživatele, skupiny nebo aplikace jako správce:

  1. Zvolte kartu Oprávnění a pak zvolte Přidat uživatele.
  2. Pomocí pole Vyhledávání vyhledejte ID uživatele, aplikaci nebo skupinu Microsoft Entra, které chcete přidat.
  3. Vyberte přiřazení role a potom zvolte Uložit.

Správa instancí

Přejděte na ikonu instance Ikona instance, kde můžete najít seznam všech instancí, vytvářet instance nebo odebírat instance.

Zobrazení využití API

Zobrazení údajů o využití rozhraní API v reálném čase.

  1. Přejděte na kartu API Management a poté vyberte kartu Využití.
  2. Vyberte časový rámec k zobrazení.

Stránka Využití rozhraní API obsahuje tři sekce:

  • Volání rozhraní API: Graf, který vizualizuje agregovaný počet volání do rozhraní API ve vybraném časovém rámci.
  • Přenos dat: Graf, který zobrazuje množství dat, která byla přenesena prostřednictvím rozhraní API ve vybraném časovém rámci.
  • Operace: Tabulka s řádky pro každou dostupnou operaci rozhraní API a podrobnostmi o využití operací.

Často kladené dotazy

Jak společnost Microsoft vypočítává emise uhlíku v cloudu zpřístupněné rozhraním API?

Informace o metodologii výpočtu společnosti Microsoft naleznete v části Metodika výpočtu rozhraní API Microsoft Cloud for Sustainability.

Kde se mohu dozvědět více o psaní dotazů pomocí OData?

Další informace o OData naleznete v článku Přehled možností dotazu.

Kde jsou uložena data použitá k vytvoření této zprávy?

Data jsou uložena ve Spojených státech.

Proč nevidím údaje o emisích za předchozí měsíc?

Údaje o emisích za daný měsíc budou k dispozici do 14. dne po skončení daného měsíce (včetně nepracovních dnů).

Nemohu vytvořit instanci. Proč?

Možná se pokoušíte přistupovat k portálu API Cloud for Sustainability účtem, který je přidružen k jinému ID tenanta hostitele, než je ten, který je uveden na registračním formuláři. Tato situace může nastat, když používáte účet hosta. Účty hostů nejsou podporovány. Pokud byste chtěli, abychom zapsali dalšího tenanta, odešlete znovu registrační formulář.

Mám jiné ID tenanta pro Microsoft 365 a Azure. Mohu přesto používat rozhraní API Microsoft Cloud for Sustainability?

Stále máte přístup k rozhraním API, ale portál nepodporuje více tenantů na instanci. Tyto tenanty budete muset k rozhraním API připojit samostatně.

Jak nakonfiguruji aplikaci pro volání rozhraní API Microsoft Cloud for Sustainability?

Máte zájem o konfiguraci aplikace pro volání rozhraní API Cloud for Sustainability? Podívejte se na tuto ukázku:

V portálu Azure přejděte na Microsoft Entra ID, vyberte Registrace aplikací a poté vyberte možnost + Nová registrace. Na stránce nové registrace zadejte název pro registraci aplikace, přizpůsobte možnosti svým potřebám a poté vyberte Registrovat. Přejděte na stránku Microsoft Entra ID, vyberte štítek Podnikové aplikace, nastavte Typ aplikace na Aplikace Microsoft a vyhledávejte podle názvu aplikace MCFS SDS. Parametr ApplicationId, který jste předali v příkazu New-AzADServicePrincipal vyžadovaný během registrace, je ApplicationId rozhraní API Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), pomocí kterého jste vytvořili instanci (podnikovou aplikaci) registrace aplikace rozhraní API Microsoft Cloud for Sustainability ve vašem vlastním tenantovi.

Když je to hotové, můžete nyní přejít na stránku registrace aplikace a vybrat Oprávnění rozhraní API. Chcete-li přidat oprávnění k registraci aplikace, aby bylo možné volat rozhraní API Microsoft Cloud for Sustainability, vyberte možnost + Přidat oprávnění a poté Rozhraní API, která moje organizace používá. Poté vyhledejte ApplicationId rozhraní API Microsoft Cloud for Sustainability (c3163bf1-092f-436b-b260-7ade5973e5b9), vyberte možnost MCFS SDS a poté vyberte oprávnění App.Emissions.Read záložky Oprávnění aplikace.

Tomuto oprávnění k typu aplikace je třeba udělit souhlas správce výběrem možnosti Udělit souhlas správce pro {your-tenant}.

Nakonec navštivte úvodní stránku rozhraní API Microsoft Cloud for Sustainability, přejděte na záložku Oprávnění a poté vyberte + Přidat. Na postranním panelu, který se zobrazí, zvolte Prohlížeč jako Role ve vstupu Uživatel, Skupina nebo Aplikace a pokračujte ve vyhledávání registrace vaší aplikace. Zvolte Uložit.

Získávám přístupový token pro svou aplikaci. Jaká je adresa URL zdroje?

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

Kolik historických dat je k dispozici?

  • Azure: Údaje o využití a emisích pokrývají posledních pět let dat souvisejících s registrací.
  • Microsoft 365: Údaje o emisích zahrnují údaje za posledních 12 měsíců spojené s předplatným Microsoft 365.

Právní doložka

Rozhraní API Microsoft Cloud for Sustainability (Preview) je založeno na oborových standardech pro výpočet uhlíku serverů a poskytuje obecné odhady, které organizacím pomáhají získat přehled o emisích uhlíku IT infrastruktury související s používáním cloudových služeb Azure. Zjištění, interpretace a závěry prezentované pomocí rozhraní API Microsoft Cloud for Sustainability (Preview), včetně výpočtů, nepředstavují konkrétní rady nebo doporučení. Vyjádřené informace a názory se mohou bez upozornění změnit. Rozhraní API Microsoft Cloud for Sustainability (Preview) je poskytováno tak, jak je, bez jakéhokoli tvrzení nebo záruky jakéhokoli druhu, ať už vyjádřené, nebo předpokládané, včetně zejména jakýchkoli prohlášení nebo doporučení týkajících se použití, výsledků nebo výkonu rozhraní API Microsoft Cloud for Sustainability (Preview), jeho vhodnost, přesnost, spolehlivost nebo správnost. Veškeré riziko spojené s používáním rozhraní API Microsoft Cloud for Sustainability (Preview) přebíráte vy. Společnost Microsoft nepřebírá odpovědnost za použití rozhraní API Microsoft Cloud for Sustainability (Preview). Společnost Microsoft nebude v žádném případě odpovědná za další přímé či nepřímé škody, včetně jakéhokoli ušlého zisku, ušlých úspor nebo jakýchkoli náhodných či následných škod vzniklých v důsledku jakýchkoli závad nebo používání či nemožnosti používat rozhraní API Microsoft Cloud for Sustainability (Preview), i když byla společnost Microsoft upozorněna na možnost takových škod.

Viz také

Příklady dotazů OData rozhraní API Microsoft Cloud for Sustainability
Metodika výpočtu rozhraní API Microsoft Cloud for Sustainability
Rozhraní API Microsoft Cloud for Sustainability