Sdílet prostřednictvím

Ověřování a autorizace pro rozhraní API služby Azure Time Series Insights

  • Článek

Poznámka

Služba Time Series Insights bude vyřazena 7. července 2024. Zvažte migraci stávajících prostředí na alternativní řešení co nejdříve. Pro více informací o vyřazení a migraci navštivte naši dokumentaci .

V závislosti na vašich obchodních potřebách může vaše řešení obsahovat jednu nebo více klientských aplikací, které používáte k interakci s rozhraními API prostředí Azure Time Series Insights. Azure Time Series Insights provádí ověřování pomocí tokenů zabezpečení Microsoft Entra založených naOAUTH 2.0 . K ověření klientů budete muset získat nosný token se správnými oprávněními a předat ho spolu s voláními rozhraní API. Tento dokument popisuje několik metod získání přihlašovacích údajů, které můžete použít k získání nosné tokeny a ověření, včetně použití spravované identity a registrace aplikace Microsoft Entra.

Spravované identity

Následující části popisují, jak použít spravovanou identitu z ID Microsoft Entra pro přístup k rozhraní API služby Azure Time Series Insights. Spravované identity v Azure eliminují potřebu vývojářů spravovat přihlašovací údaje poskytnutím identity pro prostředek Azure v Microsoft Entra ID a jeho použitím k získání tokenů Microsoft Entra. Tady jsou některé výhody používání spravovaných identit:

  • Přihlašovací údaje nemusíte spravovat. Přihlašovací údaje nejsou pro vás ani přístupné.
  • Spravované identity můžete použít k ověření v libovolné službě Azure, která podporuje ověřování Microsoft Entra, včetně služby Azure Key Vault.
  • Spravované identity je možné použít bez jakýchkoli dalších nákladů.

Další informace o dvou typech spravovaných identit najdete v Co jsou spravované identity pro prostředky Azure?

Můžete použít spravované identity z:

  • Virtuální počítače Azure
  • Azure App Services
  • Azure Functions
  • Instance kontejnerů Azure
  • a další ...

Úplný seznam najdete v službách Azure, které podporují spravované identity pro prostředky Azure.

Registrace aplikace Microsoft Entra

Pokud je to možné, doporučujeme používat spravované identity, abyste nemuseli spravovat přihlašovací údaje. Pokud vaše klientská aplikace není hostovaná ve službě Azure, která podporuje spravované identity, můžete aplikaci zaregistrovat v tenantovi Microsoft Entra. Při registraci aplikace v Microsoft Entra ID vytváříte konfiguraci identity pro vaši aplikaci, která umožňuje integraci s Microsoft Entra ID. Když zaregistrujete aplikaci na webu Azure Portal, zvolíte, jestli se jedná o jednoho tenanta (přístupného jenom ve vašem tenantovi) nebo více tenantů (přístupné v jiných tenantech) a volitelně můžete nastavit identifikátor URI přesměrování (kde se přístupový token odesílá).

Po dokončení registrace aplikace máte globálně jedinečnou instanci aplikace (objekt aplikace), která se nachází ve vašem domovském tenantovi nebo adresáři. Máte také globálně jedinečné ID aplikace (id aplikace nebo klienta). Na portálu můžete přidat tajemství nebo certifikáty a oprávnění, aby vaše aplikace fungovala, přizpůsobit branding vaší aplikace v dialogovém okně pro přihlášení a provést další úpravy.

Pokud aplikaci zaregistrujete na portálu, objekt aplikace i objekt služby se automaticky vytvoří ve vašem domovském tenantovi. Pokud zaregistrujete nebo vytvoříte aplikaci pomocí rozhraní Microsoft Graph API, vytvoření instančního objektu je samostatný krok. Objekt služby Principal je vyžadován k požádání o tokeny.

Nezapomeňte si prohlédnout kontrolní seznam zabezpečení vaší aplikace. Osvědčeným postupem je použít přihlašovací údaje certifikátu, nikoli přihlašovací údaje hesla (tajné kódy klienta).

Další podrobnosti najdete v tématu Objekty aplikace a instanční objekty v ID Microsoft Entra.

Krok 1: Vytvoření spravované identity nebo registrace aplikace

Jakmile zjistíte, jestli budete používat spravovanou identitu nebo registraci aplikace, v dalším kroku ji musíte zřídit.

Spravovaná identita

Kroky, které použijete k vytvoření spravované identity, se budou lišit v závislosti na tom, kde se váš kód nachází a jestli vytváříte identitu přiřazenou systémem nebo přiřazenou uživatelem. Přečtěte si typy spravovaných identit, abyste pochopili rozdíl. Jakmile vyberete typ identity, vyhledejte a postupujte podle správného návodu v dokumentaci o spravovaných identitách Microsoft Entra . Tady najdete pokyny ke konfiguraci spravovaných identit pro:

Registrace aplikace

Postupujte podle kroků uvedených v Registrace aplikace.

  • Po výběru příslušné platformy v kroku 4 Konfigurace nastavení platformy nakonfigurujte identifikátory URI pro přesměrování a přístupové tokeny na bočním panelu napravo od uživatelského rozhraní.

    • URI přesměrování musí odpovídat adrese zadané požadavkem na ověření:

      • U aplikací hostovaných v místním vývojovém prostředí vyberteVeřejný klient (mobilní & desktop). Nezapomeňte nastavit veřejného klienta na Ano.
      • Pro Single-Page aplikace hostované ve službě Azure App Service vyberte Web.

    • Určete, jestli je vhodná adresa URL odhlášení.

    • Povolte implicitní grantový tok zaškrtnutím přístupových tokenů nebo ID tokenů .

    Vytvořit identifikátory URI přesměrování

    Klikněte na Konfigurovata potom Uložit.

  • Připojte svou aplikaci Microsoft Entra Azure Time Series Insights. Vyberte oprávnění pro rozhraní API>Přidat oprávnění>rozhraní API používaná mou organizací.

    přiřaďte rozhraní API k aplikaci Microsoft Entra

    Do vyhledávacího panelu zadejte Azure Time Series Insights a pak vyberte Azure Time Series Insights.

  • Dále zadejte druh oprávnění rozhraní API, které vaše aplikace vyžaduje. Ve výchozím nastavení se Delegovaná oprávnění zvýrazní. Zvolte typ oprávnění a pak vyberte Přidat oprávnění.

    Určení typu oprávnění rozhraní API, které vaše aplikace vyžaduje,

  • Přidat přihlašovací údaje, pokud aplikace bude volat rozhraní API vašeho prostředí sama. Přihlašovací údaje umožňují, aby se vaše aplikace ověřila jako sama, což nevyžaduje žádnou interakci uživatele za běhu.

Krok 2: Udělení přístupu

Když vaše prostředí Azure Time Series Insights obdrží požadavek, nejprve se ověří nosný token volajícího. Pokud ověření projde, volající byl ověřen a pak se provede další kontrola, která zajistí, že volající má oprávnění k provedení požadované akce. Pokud chcete autorizovat libovolného uživatele nebo služebního principála, musíte jim nejprve udělit přístup k prostředí tím, že jim přiřadíte roli Čtenář nebo Přispěvatel.

  • Pokud chcete udělit přístup prostřednictvím uživatelského rozhraní Azure portálu, postupujte podle pokynů uvedených v článku Udělení přístupu k datům do prostředí. Když vyberete uživatele, můžete spravovanou identitu nebo registraci aplikace vyhledat podle jejího názvu nebo podle ID.

  • Pokud chcete udělit přístup pomocí Azure CLI, spusťte následující příkaz. Úplný seznam příkazů dostupných pro správu přístupu najdete v dokumentaci tady.

    az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"

Poznámka

Rozšíření timeseriesinsights pro Azure CLI vyžaduje verzi 2.11.0 nebo vyšší. Rozšíření se automaticky nainstaluje při prvním spuštění příkazu az tsi access-policy. Zjistěte více o rozšířeních.

Krok 3: Vyžádání tokenů

Jakmile je vaše spravovaná identita nebo registrace aplikace nastavena a přiřazena k ní role, můžete ji začít používat k vyžádání nosných tokenů OAuth 2.0. Metoda, kterou použijete k získání tokenu, se bude lišit v závislosti na tom, kde je váš kód hostovaný, a vámi zvolený jazyk. Při zadávání prostředku (označovaného také jako cílová skupina tokenu) můžete azure Time Series Insights identifikovat podle adresy URL nebo identifikátoru GUID:

  • https://api.timeseries.azure.com/
  • 120d688d-1518-4cf7-bd38-182f158850b6

Důležitý

Pokud jako ID prostředku použijete adresu URL, musí být token vydán přesně pro https://api.timeseries.azure.com/. Koncové lomítko je povinné.

  • Pokud používáte Postman, váš AuthURL bude: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ je platný, ale https://api.timeseries.azure.com není.

Spravované identity

Při přístupu ze služby Azure App Service nebo Functions postupujte podle pokynů v Získání tokenů pro prostředky Azure.

Pro aplikace a funkce .NET je nejjednodušší způsob, jak pracovat se spravovanou identitou, prostřednictvím klientské knihovny Azure Identity pro .NET. Tato klientská knihovna je oblíbená kvůli jednoduchosti a výhodám zabezpečení. Vývojáři můžou napsat kód jednou a nechat klientskou knihovnu určit, jak se ověřovat v závislosti na aplikačním prostředí – ať už na vývojářské pracovní stanici pomocí účtu vývojáře nebo nasazeného v Azure pomocí identity spravované služby. Pro pokyny k migraci z předchozí knihovny AppAuthentication si přečtěte Migrace z AppAuthentication do Azure.Identity - pokyny.

Vyžádání tokenu pro Azure Time Series Insights pomocí jazyka C# a klientské knihovny Azure Identity pro .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Registrace aplikace

MSAL lze použít v mnoha scénářích aplikace, včetně, ale nikoli pouze:

Ukázkový kód jazyka C# znázorňující, jak získat token jako registraci aplikace a dotazovat se na data z prostředí Gen2, najdete ukázkovou aplikaci na GitHubu

Důležitý

Pokud používáte knihovnu Azure Active Directory Authentication Library (ADAL), migrujte na MSAL.

Běžné hlavičky a parametry

Tato část popisuje běžné hlavičky a parametry požadavků HTTP používané k dotazech na rozhraní API Azure Time Series Insights Gen1 a Gen2. Požadavky specifické pro rozhraní API jsou podrobněji popsány v referenční dokumentaci k rozhraní REST API služby Azure Time Series Insights.

Spropitné

Přečtěte si referenční informace k rozhraní Azure REST API, kde najdete další informace o tom, jak využívat rozhraní REST API, provádět požadavky HTTP a zpracovávat odpovědi HTTP.

Hlavičky HTTP

Požadované hlavičky požadavků jsou popsány níže.

Požadovaná hlavička požadavku Popis
Oprávnění K ověření pomocí služby Azure Time Series Insights je nutné předat platný nosný token OAuth 2.0 v hlavičce autorizace .

Spropitné

Přečtěte si ukázkovou vizualizaci klientské sady SDK služby Azure Time Series Insights, ve které se dozvíte, jak se ověřovat pomocí rozhraní API služby Azure Time Series Insights prostřednictvím kódu programu pomocí javascriptové klientské sady SDK spolu s grafy a grafy.

Volitelné hlavičky požadavků jsou popsány níže.

Volitelná hlavička požadavku Popis
Typ obsahu podporuje se pouze application/json.
x-ms-client-request-id Identifikátor požadavku klienta. Služba tuto hodnotu zaznamená. Umožňuje službě trasovat operace napříč službami.
x-ms-client-session-id ID klientské relace. Služba tuto hodnotu zaznamená. Umožňuje službě trasovat skupinu souvisejících operací napříč službami.
x-ms-client-application-name (název klientské aplikace) Název aplikace, která tuto žádost vygenerovala. Služba tuto hodnotu zaznamená.

Volitelné, ale doporučené hlavičky odpovědi jsou popsány níže.

Hlavička odpovědi Popis
Typ obsahu Podporuje se pouze application/json.
x-ms-request-id ID požadavku generovaného serverem. Můžete ho použít ke kontaktování Microsoftu a prošetřit žádost.
x-ms-property-not-found-behavior Volitelná hlavička odpovědi GA API. Možné hodnoty jsou ThrowError (výchozí) nebo UseNull.

Parametry HTTP

Spropitné

Další informace o požadovaných a volitelných dotazech najdete v referenční dokumentaci .

Požadované parametry řetězce dotazu adresy URL závisí na verzi rozhraní API.

Uvolnit Hodnoty verzí rozhraní API
Gen1 api-version=2016-12-12
Gen2 api-version=2020-07-31

Volitelné parametry řetězce dotazu adresy URL zahrnují nastavení časového limitu pro časy provádění požadavků HTTP.

Volitelný parametr dotazu Popis Verze
timeout=<timeout> Časový limit na straně serveru pro spuštění požadavku HTTP Platí pouze pro rozhraní API získání událostí prostředí a získání agregací prostředí. Hodnota časového limitu by měla být ve formátu doby trvání ISO 8601, například "PT20S" a měla by být v rozsahu 1-30 s. Výchozí hodnota je 30 s. Gen1
storeType=<storeType> Pro prostředí Gen2 s povoleným teplým úložištěm je možné dotaz spustit buď na WarmStore, nebo ColdStore. Tento parametr v dotazu definuje, na kterém úložišti se má dotaz spustit. Pokud není definovaný, dotaz se spustí v studeném úložišti. Pokud chcete zadat dotaz na teplé úložiště, storeType musí být nastavena na WarmStore. Pokud není definovaný, dotaz se spustí v studeném úložišti. Gen2

Další kroky