Udostępnij za pośrednictwem

Uwierzytelnianie i autoryzacja na potrzeby interfejsu API usługi Azure Time Series Insights

  • Artykuł

Uwaga

Usługa Time Series Insights zostanie wycofana 7 lipca 2024 r. Rozważ migrację istniejących środowisk do alternatywnych rozwiązań tak szybko, jak to możliwe. Aby uzyskać więcej informacji na temat wycofywania i migracji, odwiedź naszą dokumentację.

W zależności od potrzeb biznesowych rozwiązanie może zawierać co najmniej jedną aplikację kliencą używaną do interakcji z interfejsami API środowiska usługi Azure Time Series Insights. Usługa Azure Time Series Insights przeprowadza uwierzytelnianie przy użyciu tokenów zabezpieczeń firmy Microsoft w oparciu o protokół OAUTH 2.0. Aby uwierzytelnić klientów, musisz uzyskać token elementu nośnego z odpowiednimi uprawnieniami i przekazać go wraz z wywołaniami interfejsu API. W tym dokumencie opisano kilka metod pobierania poświadczeń, których można użyć do uzyskania tokenu elementu nośnego i uwierzytelnienia, w tym przy użyciu tożsamości zarządzanej i rejestracji aplikacji Microsoft Entra.

Tożsamości zarządzane

W poniższych sekcjach opisano sposób używania tożsamości zarządzanej z usługi Microsoft Entra ID w celu uzyskania dostępu do interfejsu API usługi Azure Time Series Insights. Na platformie Azure zarządzane tożsamości eliminują potrzebę zarządzania poświadczeniami przez deweloperów, zapewniając tożsamość dla zasobu Azure w Microsoft Entra ID i używając jej do uzyskiwania tokenów Microsoft Entra. Poniżej przedstawiono niektóre korzyści wynikające z używania tożsamości zarządzanych:

  • Nie potrzebujesz zarządzać poświadczeniami. Poświadczenia nie są nawet dostępne dla Ciebie.
  • Tożsamości zarządzane można używać do uwierzytelniania w dowolnej usłudze platformy Azure, która obsługuje uwierzytelnianie firmy Microsoft Entra, w tym usługę Azure Key Vault.
  • Tożsamości zarządzane mogą być używane bez dodatkowych kosztów.

Aby uzyskać więcej informacji na temat dwóch typów tożsamości zarządzanych, przeczytaj Co to są tożsamości zarządzane dla zasobów platformy Azure?

Tożsamości zarządzane można używać z poziomu:

  • Maszyny wirtualne platformy Azure
  • Azure App Services
  • Azure Functions
  • Wystąpienia kontenerów platformy Azure
  • i więcej ...

Aby uzyskać pełną listę, zobacz Usługi platformy Azure, które obsługują tożsamości zarządzane dla zasobów platformy Azure.

Rejestracja aplikacji Microsoft Entra

Zalecamy używanie tożsamości zarządzanych zawsze, gdy jest to możliwe, aby nie trzeba było zarządzać poświadczeniami. Jeśli aplikacja kliencka nie jest hostowana w usłudze platformy Azure, która obsługuje tożsamości zarządzane, możesz zarejestrować aplikację w dzierżawie firmy Microsoft Entra. Podczas rejestrowania aplikacji przy użyciu identyfikatora Entra firmy Microsoft tworzysz konfigurację tożsamości dla aplikacji, która umożliwia jej integrację z identyfikatorem Entra firmy Microsoft. Podczas rejestrowania aplikacji w witrynie Azure Portal możesz wybrać, czy jest to jedna dzierżawa (dostępna tylko w dzierżawie), czy wielodostępna (dostępna w innych dzierżawach) i opcjonalnie może ustawić identyfikator URI przekierowania (do którego jest wysyłany token dostępu).

Po zakończeniu rejestracji aplikacji masz globalnie unikatowe wystąpienie aplikacji (obiektu aplikacji), które znajduje się w dzierżawie głównej lub katalogu. Masz również unikatowy identyfikator globalny dla aplikacji (identyfikator aplikacji lub klienta). W portalu możesz następnie dodać wpisy tajne lub certyfikaty i zakresy, aby aplikacja działała, dostosować znakowanie aplikacji w oknie dialogowym logowania i nie tylko.

Jeśli zarejestrujesz aplikację w portalu, obiekt aplikacji, a także obiekt jednostki usługi zostaną automatycznie utworzone w dzierżawie głównej. Jeśli zarejestrujesz/utworzysz aplikację przy użyciu interfejsów API programu Microsoft Graph, tworzenie obiektu jednostki usługi jest osobnym krokiem. Obiekt jednostki usługi jest wymagany do żądania tokenów.

Zapoznaj się z listą kontrolną zabezpieczeń dla aplikacji. Najlepszym rozwiązaniem jest użycie poświadczeń certyfikatu, a nie poświadczeń haseł (wpisów tajnych klienta).

Aby uzyskać więcej informacji, zobacz Application and service principal objects in Microsoft Entra ID (Obiekty aplikacji i jednostki usługi w identyfikatorze entra firmy Microsoft).

Krok 1. Tworzenie tożsamości zarządzanej lub rejestracji aplikacji

Po określeniu, czy będziesz używać tożsamości zarządzanej, czy rejestracji aplikacji, następnym krokiem jest aprowizuj ją.

Tożsamość zarządzana

Kroki używane do utworzenia tożsamości zarządzanej różnią się w zależności od lokalizacji kodu i tego, czy tworzysz tożsamość przypisaną przez system, czy przypisaną przez użytkownika. Przeczytaj typy tożsamości zarządzanych , aby zrozumieć różnicę. Po wybraniu typu tożsamości znajdź i postępuj zgodnie z poprawnym samouczkiem w dokumentacji tożsamości zarządzanych firmy Microsoft Entra. W tym miejscu znajdziesz instrukcje dotyczące konfigurowania tożsamości zarządzanych dla:

Rejestrowanie aplikacji

Wykonaj kroki wymienione w temacie Rejestrowanie aplikacji.

  • Po wybraniu odpowiedniej platformy w kroku 4 sekcji Konfigurowanie ustawień platformy skonfiguruj identyfikatory URI przekierowania i tokeny dostępu na panelu bocznym po prawej stronie interfejsu użytkownika.

    • Identyfikatory URI przekierowania muszą być zgodne z adresem dostarczonym przez żądanie uwierzytelniania:

      • W przypadku aplikacji hostowanych w lokalnym środowisku programistycznym wybierz pozycję Klient publiczny (mobilny i klasyczny). Upewnij się, że dla klienta publicznego ustawiono wartość Tak.
      • W przypadku aplikacji jednostronicowych hostowanych w usłudze aplikacja systemu Azure wybierz pozycję Sieć Web.

    • Ustal, czy adres URL wylogowywania jest odpowiedni.

    • Włącz niejawny przepływ udzielania, sprawdzając tokeny dostępu lub tokeny identyfikatorów.

    Tworzenie identyfikatorów URI przekierowania

    Kliknij pozycję Konfiguruj, a następnie pozycję Zapisz.

  • Skojarz aplikację Microsoft Entra z usługą Azure Time Series Insights. Wybierz pozycję Uprawnienia>interfejsu API Dodaj interfejsy API uprawnień>używane przez moją organizację.

    Kojarzenie interfejsu API z aplikacją Microsoft Entra

    Wpisz Azure Time Series Insights na pasku wyszukiwania, a następnie wybierz pozycję Azure Time Series Insights.

  • Następnie określ rodzaj uprawnienia interfejsu API wymagane przez aplikację. Domyślnie uprawnienia delegowane zostaną wyróżnione. Wybierz typ uprawnień, a następnie wybierz pozycję Dodaj uprawnienia.

    Określanie rodzaju uprawnień interfejsu API wymaganego przez aplikację

  • Dodaj poświadczenia , jeśli aplikacja będzie wywoływać interfejsy API środowiska jako same. Poświadczenia umożliwiają aplikacji uwierzytelnianie się jako sama, bez konieczności interakcji z użytkownikiem w czasie wykonywania.

Krok 2. Udzielanie dostępu

Gdy środowisko usługi Azure Time Series Insights odbiera żądanie, najpierw jest weryfikowany token elementu nośnego wywołującego. Jeśli weryfikacja zakończy się pomyślnie, obiekt wywołujący został uwierzytelniony, a następnie zostanie wykonane kolejne sprawdzenie, aby upewnić się, że obiekt wywołujący ma autoryzację do wykonania żądanej akcji. Aby autoryzować dowolnego użytkownika lub jednostki usługi, musisz najpierw przyznać im dostęp do środowiska, przypisując im rolę Czytelnik lub Współautor.

  • Aby udzielić dostępu za pośrednictwem interfejsu użytkownika witryny Azure Portal , postępuj zgodnie z instrukcjami wymienionymi w artykule Udzielanie dostępu do danych do środowiska . Po wybraniu użytkownika możesz wyszukać tożsamość zarządzaną lub rejestrację aplikacji według jego nazwy lub identyfikatora.

  • Aby udzielić dostępu przy użyciu interfejsu wiersza polecenia platformy Azure, uruchom następujące polecenie. Zapoznaj się z dokumentacją tutaj , aby uzyskać pełną listę poleceń dostępnych do zarządzania dostępem.

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

Uwaga

Rozszerzenie timeseriesinsights dla interfejsu wiersza polecenia platformy Azure wymaga wersji 2.11.0 lub nowszej. Rozszerzenie zostanie automatycznie zainstalowane przy pierwszym uruchomieniu polecenia az tsi access-policy. Dowiedz się więcej o rozszerzeniach.

Krok 3. Żądanie tokenów

Gdy tożsamość zarządzana lub rejestracja aplikacji została aprowizowana i przypisana rola, możesz rozpocząć korzystanie z niej w celu żądania tokenów elementu nośnego OAuth 2.0. Metoda używana do uzyskania tokenu będzie się różnić w zależności od tego, gdzie jest hostowany kod i wybrany język. Podczas określania zasobu (znanego również jako "odbiorcy" tokenu) można zidentyfikować usługę Azure Time Series Insights według jego adresu URL lub identyfikatora GUID:

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

Ważne

Jeśli używasz adresu URL jako identyfikatora zasobu, token musi być wystawiony dokładnie na https://api.timeseries.azure.com/. Wymagany jest ukośnik końcowy.

  • W przypadku korzystania z narzędzia Postman adres AuthURL będzie zatem: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
  • https://api.timeseries.azure.com/ jest prawidłowy, ale https://api.timeseries.azure.com nie.

Tożsamości zarządzane

Podczas uzyskiwania dostępu z usługi aplikacja systemu Azure lub funkcji postępuj zgodnie ze wskazówkami w temacie Uzyskiwanie tokenów dla zasobów platformy Azure.

W przypadku aplikacji i funkcji platformy .NET najprostszym sposobem pracy z tożsamością zarządzaną jest biblioteka klienta tożsamości platformy Azure dla platformy .NET. Ta biblioteka kliencka jest popularna ze względu na prostotę i zalety zabezpieczeń. Deweloperzy mogą pisać kod raz i pozwolić bibliotece klienta określić sposób uwierzytelniania na podstawie środowiska aplikacji — niezależnie od tego, czy na stacji roboczej dewelopera przy użyciu konta dewelopera, czy wdrożonego na platformie Azure przy użyciu tożsamości usługi zarządzanej. Aby uzyskać wskazówki dotyczące migracji z poprzedniej biblioteki AppAuthentication, przeczytaj Artykuł AppAuthentication to Azure.Identity Migration Guidance (Wskazówki dotyczące migracji w usłudze AppAuthentication).

Zażądaj tokenu dla usługi Azure Time Series Insights przy użyciu języka C# i biblioteki klienta tożsamości platformy Azure dla platformy .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;

Rejestracja aplikacji

Biblioteka MSAL może być używana w wielu scenariuszach aplikacji, w tym w następujących sytuacjach:

Przykładowy kod języka C# przedstawiający sposób uzyskiwania tokenu jako rejestracji aplikacji i wykonywania zapytań dotyczących danych ze środowiska Gen2 można wyświetlić przykładową aplikację w usłudze GitHub

Ważne

Jeśli używasz biblioteki Azure Active Directory Authentication Library (ADAL), przeprowadź migrację do biblioteki MSAL.

Typowe nagłówki i parametry

W tej sekcji opisano typowe nagłówki i parametry żądania HTTP używane do wykonywania zapytań względem interfejsów API usługi Azure Time Series Insights Gen1 i Gen2. Wymagania specyficzne dla interfejsu API zostały szczegółowo omówione w dokumentacji interfejsu API REST usługi Azure Time Series Insights.

Napiwek

Przeczytaj dokumentację interfejsu API REST platformy Azure, aby dowiedzieć się więcej na temat korzystania z interfejsów API REST, tworzenia żądań HTTP i obsługi odpowiedzi HTTP.

Nagłówki HTTP

Wymagane nagłówki żądań zostały opisane poniżej.

Wymagany nagłówek żądania opis
Autoryzacja Aby uwierzytelnić się w usłudze Azure Time Series Insights, należy przekazać prawidłowy token elementu nośnego OAuth 2.0 w nagłówku autoryzacji.

Napiwek

Przeczytaj przykładową wizualizację przykładowego zestawu SDK klienta usługi Azure Time Series Insights, aby dowiedzieć się, jak uwierzytelniać się za pomocą interfejsów API usługi Azure Time Series Insights programowo przy użyciu zestawu SDK klienta języka JavaScript wraz z wykresami i wykresami.

Opcjonalne nagłówki żądań zostały opisane poniżej.

Opcjonalny nagłówek żądania opis
Typ zawartości obsługiwane jest tylko application/json .
x-ms-client-request-id Identyfikator żądania klienta. Usługa rejestruje tę wartość. Umożliwia usłudze śledzenie operacji między usługami.
x-ms-client-session-id Identyfikator sesji klienta. Usługa rejestruje tę wartość. Umożliwia usłudze śledzenie grupy powiązanych operacji między usługami.
x-ms-client-application-name Nazwa aplikacji, która wygenerowała to żądanie. Usługa rejestruje tę wartość.

Opcjonalne, ale zalecane nagłówki odpowiedzi zostały opisane poniżej.

Nagłówek odpowiedzi opis
Typ zawartości Obsługiwany jest tylko warunek application/json.
x-ms-request-id Identyfikator żądania wygenerowanego przez serwer. Może służyć do kontaktowania się z firmą Microsoft w celu zbadania żądania.
x-ms-property-not-found-behavior Opcjonalny nagłówek odpowiedzi interfejsu API ga. Możliwe wartości to ThrowError (wartość domyślna) lub UseNull.

Parametry HTTP

Napiwek

Więcej informacji na temat wymaganych i opcjonalnych informacji o kwerendach można znaleźć w dokumentacji referencyjnej.

Wymagane parametry ciągu zapytania adresu URL zależą od wersji interfejsu API.

Zwolnij Wartości wersji interfejsu API
Gen1 api-version=2016-12-12
Druga generacja api-version=2020-07-31

Opcjonalne parametry ciągu zapytania adresu URL obejmują ustawienie limitu czasu dla czasów wykonywania żądań HTTP.

Opcjonalny parametr zapytania opis Wersja
timeout=<timeout> Limit czasu po stronie serwera na potrzeby wykonywania żądań HTTP. Dotyczy tylko interfejsów API Uzyskiwanie zdarzeń środowiska i Uzyskiwanie agregacji środowiska. Wartość limitu czasu powinna być w formacie czasu trwania ISO 8601, na przykład "PT20S" i powinna być w zakresie 1-30 s. Wartość domyślna to 30 s. Gen1
storeType=<storeType> W przypadku środowisk gen2 z włączonym ciepłym magazynem zapytanie można wykonać na obiekcie WarmStore lub ColdStore. Ten parametr w zapytaniu definiuje, w którym magazynie ma być wykonywane zapytanie. Jeśli nie zostanie zdefiniowana, zapytanie zostanie wykonane w magazynie zimnym. Aby wysłać zapytanie dotyczące ciepłego magazynu, parametr storeType należy ustawić na WarmStorewartość . Jeśli nie zostanie zdefiniowana, zapytanie zostanie wykonane względem magazynu zimnego. Druga generacja

Następne kroki