Publikowanie usługi Microsoft Azure Data Manager for Energy API w zabezpieczonej bramie interfejsu API

Usługa Azure API Management pełni kluczową rolę pośrednika między aplikacjami klienckimi i interfejsami API zaplecza. Ułatwia klientom dostęp do usług, ukrywając szczegóły techniczne i zapewniając organizacjom kontrolę nad zabezpieczeniami interfejsu API.

Publikując interfejsy API usługi Azure Data Manager for Energy za pośrednictwem usługi Azure API Management, możesz użyć funkcji usługi Azure Data Manager for Energy Private Link dla ruchu prywatnego i całkowicie usunąć bezpośredni publiczny dostęp do wystąpienia.

W tym artykule opisano sposób konfigurowania usługi Azure API Management na potrzeby zabezpieczania usługi Azure Data Manager dla interfejsów API energii.

Wymagania wstępne

Do ukończenia tego przewodnika potrzebne są następujące składniki, narzędzia i informacje:

• Sieć wirtualna z dwiema dostępnymi podsieciami— jedną dla prywatnego punktu końcowego usługi Azure Data Manager for Energy i drugą dla iniekcji sieci wirtualnej usługi Azure API Management.

• Usługa Azure Data Manager for Energy skonfigurowana za pomocą łącza prywatnego wdrożonego w podsieci.

• Usługa Azure API Management została aprowizowana i wdrożona w sieci wirtualnej przy użyciu iniekcji sieci wirtualnej. Wybierz pozycję Tryb zewnętrzny lub zobacz sekcję Inne opcje dla trybu wewnętrznego .

• Edytor kodu, taki jak Visual Studio Code , do modyfikowania specyfikacji interfejsu OpenAPI usługi Azure Data Manager for Energy dla każdego publikowanego interfejsu API.

• Pobierz specyfikacje interfejsu OpenAPI usługi Azure Data Manager for Energy z repozytorium GitHub adme-samples . Przejdź do katalogu rest-apis i wybierz odpowiednią wersję aplikacji.

• Z poziomu rejestracji aplikacji usługi Azure Data Manager for Energy, która została użyta w czasie aprowizacji, zanotuj identyfikator dzierżawy i identyfikator klienta:

  

Przygotowywanie wystąpienia usługi API Management

Wykonaj następujące kroki, aby wprowadzić zmiany konfiguracji w wystąpieniu usługi Azure API Management:

1. W okienku Wszystkie zasoby wybierz wystąpienie usługi Azure API Management używane na potrzeby tego przewodnika.

2. Przejdź do strony Ustawienia produktów, wybierając ją z grupy ustawień interfejsu API:

   

3. Na stronie Produkty wybierz przycisk Dodaj, aby utworzyć nowy produkt. Produkty usługi Azure API Management umożliwiają tworzenie luźno powiązanej grupy interfejsów API, którymi można zarządzać i zarządzać razem. Tworzymy produkt dla naszych interfejsów API usługi Azure Data Manager for Energy.

4. Na stronie Dodawanie produktu wprowadź wartości opisane w poniższej tabeli, aby utworzyć produkt.

   

   Ustawienie	Wartość
   Wyświetlana nazwa	"Azure Data Manager for Energy Product"
   ID	"adme-product"
   opis	Wprowadź opis wskazujący deweloperom, którzy interfejsy API grupujemy
   Opublikowany	Zaznacz to pole, aby opublikować utworzony produkt
   Wymaga subskrypcji	Zaznacz to pole, aby zapewnić podstawową autoryzację dla naszych interfejsów API
   Wymaga zatwierdzenia	Opcjonalnie wybierz, jeśli chcesz, aby administrator przeglądał i akceptował lub odrzucał próby subskrypcji tego produktu. Jeśli nie wybrano, próby subskrypcji zostaną automatycznie zatwierdzone.
   Limit liczby subskrypcji	Opcjonalnie ogranicz liczbę wielu równoczesnych subskrypcji.
   Postanowienia prawne	Opcjonalnie zdefiniuj warunki użytkowania produktu, który subskrybenci muszą zaakceptować w celu korzystania z produktu.
   Interfejsy API	Możemy zignorować tę funkcję. W dalszej części tego artykułu skojarzymy interfejsy API

5. Wybierz pozycję Utwórz , aby utworzyć nowy produkt.

6. Po zakończeniu tworzenia produktu portal powróci do strony Produkty. Wybierz nowo utworzony produkt Azure Data Manager for Energy Product , aby przejść do strony Zasób produktu. Wybierz element menu Ustawienia zasad z menu ustawień.

   

7. W okienku Przetwarzanie przychodzące wybierz ikonę </> , która umożliwia modyfikowanie zasad dla produktu. Dodasz trzy zestawy zasad, aby zwiększyć bezpieczeństwo rozwiązania:

   • Zweryfikuj token identyfikatora entra, aby upewnić się, że nieuwierzytelnione żądania są przechwytywane w bramie interfejsu API
   • Limit przydziału i szybkości w celu kontrolowania szybkości żądań i łącznej liczby żądań/przesyłanych danych
   • Ustaw nagłówek , aby usunąć nagłówki zwracane przez interfejsy API zaplecza, co może spowodować ujawnienie poufnych szczegółów potencjalnym złym aktorom

8. Dodaj następujące zasady validate-azure-ad-token do naszej konfiguracji w tagach przychodzących i poniżej tagu podstawowego. Pamiętaj, aby zaktualizować szablon przy użyciu szczegółów aplikacji Microsoft Entra ID zanotowany w wymaganiach wstępnych.

   <validate-azure-ad-token tenant-id="INSERT_TENANT_ID">
       <client-application-ids>
           <application-id>INSERT_APP_ID</application-id>
       </client-application-ids>
   </validate-azure-ad-token>
   

9. Poniżej zasad validate-azure-ad-token dodaj następujące zasady limitu przydziału i limitu szybkości. Zaktualizuj wartości konfiguracji zasad odpowiednio dla użytkowników.

   <rate-limit calls="20" renewal-period="90" remaining-calls-variable-name="remainingCallsPerSubscription"/>
   <quota calls="10000" bandwidth="40000" renewal-period="3600" />
   

10. W sekcji ruchu wychodzącego edytora zasad i w obszarze tagu podstawowego dodaj następujące zasady set-header.

    <set-header name="x-envoy-upstream-service-time" exists-action="delete" />
    <set-header name="x-internal-uri-pattern" exists-action="delete" />
    

11. Wybierz pozycję Zapisz, aby potwierdzić zmiany.

    

12. Wróć do zasobu usługi API Management w witrynie Azure Portal. Wybierz element menu Zaplecza i wybierz przycisk + Dodaj.

    

13. W modalnym zapleczu wprowadź wartości opisane w poniższej tabeli, aby utworzyć zaplecze.

    Ustawienie	Wartość
    Nazwisko	"adme-backend"
    opis	Wprowadź opis wskazujący deweloperom, że to zaplecze jest związane z usługą Azure Data Manager for Energy API
    Typ	Niestandardowy adres URL
    Adres URL środowiska uruchomieniowego	Wprowadź _ex identyfikatora URI usługi Azure Data Manager for Energy. https://INSERT_ADME_NAME.energy.azure.com/
    Weryfikowanie łańcucha certyfikatów	Zaznaczone
    Weryfikowanie nazwy certyfikatu	Zaznaczone

    

14. Wybierz pozycję Utwórz , aby utworzyć zaplecze. Nowo utworzone zaplecze będzie używane w następnej sekcji podczas publikowania interfejsów API.

Importowanie usługi Azure Data Manager dla interfejsów API energii

Wykonaj następujące kroki, aby zaimportować, skonfigurować i opublikować interfejsy API usługi Azure Data Manager for Energy w bramie usługi Azure API Management:

1. Wróć do wystąpienia usługi Azure API Management używanego w ostatniej sekcji.

2. Wybierz element menu Interfejsy API z menu, a następnie wybierz przycisk + Dodaj interfejs API .

3. Wybierz pozycję OpenAPI w obszarze nagłówka Create from definition (Utwórz na podstawie definicji ).

   

4. W oknie modalnym tworzenia specyfikacji interfejsu OpenAPI wybierz przełącznik Pełny.

5. Znajdź specyfikacje interfejsu OpenAPI pobrane w ramach wymagań wstępnych i otwórz specyfikację schematu przy użyciu wybranego edytora kodu. Wyszukaj wyraz "serwer" i zanotuj adres URL serwera w pliku np. /api/schema-service/v1/.

6. Wybierz pozycję Wybierz plik i wybierz specyfikację interfejsu API schematu. Po zakończeniu przekazywania okno modalne ładuje niektóre wartości ze specyfikacji.

7. W przypadku innych pól wprowadź wartości opisane w poniższej tabeli:

   Ustawienie	Wartość
   Uwzględnij wymagane parametry zapytania w szablonach operacji	Zaznaczone
   Display name	Wprowadź nazwę wyświetlaną, która ma sens dla deweloperów aplikacji, np. Azure Data Manager for Energy Schema Service
   Nazwisko	Usługa API Management sugeruje nazwę kebab-cased. Opcjonalnie można zmienić nazwę, ale musi być unikatowa dla wystąpienia
   opis	Specyfikacja interfejsu OpenAPI może definiować opis, jeśli tak jest automatycznie wypełniany opis. Opcjonalnie zaktualizuj opis dla danego przypadku użycia.
   Schemat adresu URL	Wybierz pozycję "Oba"
   Sufiks adresu URL interfejsu API	Wprowadź sufiks dla wszystkich interfejsów API usługi Azure Data Manager for Energy (np. adme). Następnie wprowadź adres URL serwera z kroku 5. Ostateczna wartość powinna wyglądać następująco: /adme/api/schema-service/v1/. Sufiks umożliwia zgodność z istniejącymi klientami i zestawami programistycznymi, które zwykle łączą się bezpośrednio z usługą Azure Data Manager dla interfejsów API energii
   Tagi	Opcjonalnie wprowadź tagi
   Produkty	Wybierz produkt "Azure Data Manager for Energy" utworzony w poprzedniej sekcji

   Ważne

   Zweryfikuj sufiks adresu URL interfejsu API. Jest to częsta przyczyna błędów podczas publikowania interfejsów API usługi Azure Data Manager for Energy

8. Wybierz pozycję Utwórz , aby utworzyć fasadę interfejsu API.

   

9. Wybierz nowo utworzoną fasadę interfejsu API schematu z listy interfejsów API i wybierz pozycję Wszystkie operacje na liście operacji. W okienku Przetwarzanie przychodzące wybierz ikonę< />, aby edytować dokument zasad.

   

10. Aby skonfigurować interfejs API, dodaj dwa zestawy zasad:

    • Ustawianie usługi zaplecza w celu kierowania żądań do wystąpienia usługi Azure Data Manager for Energy
    • Zapisz ponownie identyfikator URI , aby usunąć prefiks adme i skompilować żądanie do interfejsu API zaplecza. Ta instrukcja zasad używa wyrażeń zasad do dynamicznego dodawania wartości szablonu adresu URL bieżącej operacji do adresu URL serwera.

11. Zanotuj adres URL serwera z kroku 5. Poniżej tagu podstawowego w sekcji ruchu przychodzącego wstaw następujące dwie instrukcje zasad.

    <set-backend-service backend-id="adme-backend" />
    

    <!-- replace the '/api/schema-service/v1' with the server URL for this API specification you noted in step 5 -->
    <rewrite-uri template="@{return "/api/schema-service/v1"+context.Operation.UrlTemplate;}" />
    

12. Wybierz pozycję Zapisz, aby potwierdzić zmiany.

13. Przetestuj interfejs API, wybierając operację POBIERZ informacje o wersji z listy operacji. Następnie wybierz kartę Test, aby przejść do konsoli testowej usługi Azure API Management.

14. Wprowadź wartości opisane w poniższej tabeli. Wygeneruj token uwierzytelniania dla usługi Azure Data Manager for Energy. Wybierz pozycję Wyślij , aby przetestować interfejs API.

    Ustawienie	Wartość
    data-partition-id	Identyfikator partycji danych dla wystąpienia usługi Azure Data Manager for Energy
    Rezultat	Wybierz utworzony wcześniej produkt Azure Data Manager for Energy
    Autoryzacja	"Element nośny" i wygenerowany token uwierzytelniania

    

15. Jeśli interfejs API jest poprawnie skonfigurowany, powinna zostać wyświetlona odpowiedź HTTP 200 — OK , która wygląda podobnie do zrzutu ekranu. Jeśli nie, zapoznaj się z sekcją Rozwiązywanie problemów.

16. Powtórz powyższe kroki dla każdego interfejsu API usługi Azure Data Manager for Energy i skojarzonej specyfikacji.

Rozwiązywanie problemów

Podczas testowania interfejsów API za pośrednictwem usługi Azure API Management występują błędy, które zwykle wskazują na problemy z konfiguracją. Na podstawie błędu przejrzyj potencjalne kroki rozwiązywania problemów.

Kod	Komunikat o błędzie	Szczegóły
HTTP 401 Unauthorized	Invalid Azure AD JWT	Upewnij się, że masz prawidłowy nagłówek uwierzytelniania dla dzierżawy microsoft Entra ID i aplikacji klienckiej dla wystąpienia usługi Azure Data Manager for Energy.
HTTP 401 Unauthorized	Azure AD JWT not present	Upewnij się, że nagłówek uwierzytelniania został dodany do żądania testowego.
HTTP 404 Not Found		Ten błąd zazwyczaj oznacza, że żądanie do interfejsu API zaplecza jest wykonywane pod nieprawidłowym adresem URL. Śledzenie żądania interfejsu API w usłudze API Management w celu zrozumienia, jaki adres URL jest generowany dla żądania zaplecza i upewnij się, że jest prawidłowy. Jeśli tak nie jest, sprawdź ponownie zasady lub zaplecze adresu URL.
HTTP 500 Internal Server Error	Internal server error	Ten błąd zwykle odzwierciedla problem z wysyłaniem żądań do interfejsu API zaplecza. Zwykle w tym scenariuszu problem dotyczy usług nazw domen (DNS). Upewnij się, że w sieci wirtualnej skonfigurowano prywatną strefę DNS lub że niestandardowe rozpoznawanie nazw DNS ma odpowiednie usługi przesyłania dalej. Śledzenie żądania interfejsu API w usłudze API Management w celu zrozumienia, jakie żądanie zaplecza zostało wykonane i jakie błędy zgłasza usługa API Management podczas próby wysłania żądania.

Inne uwagi

Wewnętrzny tryb sieci wirtualnej usługi API Management

Tryb wewnętrzny całkowicie izoluje usługę Azure API Management zamiast ujawniać punkty końcowe za pośrednictwem publicznego adresu IP. W tej konfiguracji organizacje mogą zapewnić, że wszystkie usługi Azure Data Manager for Energy są wewnętrzne. Ponieważ usługa Azure Data Manager for Energy to rozwiązanie do współpracy z partnerami i klientami, ten scenariusz może nie być korzystny.

Usługa App Gateway z zaporą aplikacji internetowej

Zamiast korzystać tylko z wewnętrznego trybu sieci wirtualnej, wiele organizacji decyduje się na zastosowanie zabezpieczonego mechanizmu zwrotnego serwera proxy w celu uwidocznienia wystąpienia usługi Azure API Management w trybie wewnętrznym dla partnerów zewnętrznych i klientów. Wystąpienie trybu wewnętrznego pozostaje w pełni odizolowane za pomocą ściśle kontrolowanego ruchu przychodzącego, który musi przechodzić przez serwer proxy.

aplikacja systemu Azure Gateway to wspólna usługa do użycia jako zwrotny serwer proxy. aplikacja systemu Azure Gateway ma również funkcję zapory aplikacji internetowej (WAF), która aktywnie wykrywa potencjalne ataki na luki w zabezpieczeniach aplikacji i interfejsów API.

Konfigurowanie usługi Azure API Management przy użyciu domeny niestandardowej

Inną typową cechą tej architektury jest zastosowanie domeny niestandardowej do interfejsów API. Chociaż usługa Azure Data Manager for Energy nie obsługuje tej funkcji, zamiast tego można skonfigurować domenę niestandardową w usłudze Azure API Management.

Certyfikat dla domeny jest wymaganiem wstępnym. Jednak usługa Azure API Management obsługuje tworzenie bezpłatnych certyfikatów zarządzanych dla domeny niestandardowej.

Powiązana zawartość

• Punkt odniesienia zabezpieczeń platformy Azure dla usługi API Management

• Punkt odniesienia zabezpieczeń platformy Azure dla usługi Azure Data Manager for Energy

• Samouczek: tworzenie bramy aplikacji z usługą Web Application Firewall przy użyciu witryny Azure Portal