Tworzenie łącznika niestandardowego dla interfejsu API sieci Web

W tym samouczku pokazano, jak rozpocząć tworzenie internetowego interfejsu API ASP.NET, hostować go jako funkcji aplikacji sieci Web systemu Azure w usłudze Azure App Service, włączyć uwierzytelnianie tożsamością Microsoft Entra, a następnie zarejestrować internetowy interfejs API ASP.NET w usłudze Power Automate. Po zarejestrowaniu interfejsu API można połączyć się z nim i wywołać go z przepływu. Możesz również zarejestrować interfejs API i wywoływać go z poziomu usługi Power Apps lub Azure Logic Apps.

Wymagania wstępne

Tworzenie i wdrażanie aplikacji sieci Web ASP.NET w Azure

W tym samouczku utworzysz aplikację sieci Web ASP.NET Visual C#.

  1. Otwórz Visual Studio, a następnie wybierz Plik > Nowy projekt.

    1. Rozwiń węzeł Zainstalowane, przejdź do pozycji Szablony > Visual C# > Sieć Web, i wybierz pozycję Aplikacja internetowa ASP.NET.

    2. Wprowadź nazwę projektu, lokalizację i nazwę rozwiązania dla swojej aplikacji, a następnie wybierz OK.

    Zrzut ekranu przedstawiający nową aplikację sieci Web języka Visual C# ASP.NET.

  2. W polu Nowa aplikacja internetowa ASP.NET wybierz szablon Web API, upewnij się, że zaznaczone jest pole wyboru Host w chmurze, a następnie wybierz Zmień uwierzytelnianie.

    Zrzut ekranu przedstawiający okno dialogowe Nowa aplikacja sieci Web ASP.NET.

  3. Wybierz pozycję Bez uwierzytelniania, a następnie kliknij przycisk OK. Uwierzytelnienie można skonfigurować później.

    Wybierz Brak uwierzytelnienia.

  4. Kiedy pojawi się okno Nowa aplikacja ASP.NET sieci Web, wybierz OK.

  5. W polu Utwórz aplikację App Service sprawdź ustawienia hostingu opisane w tabeli, wprowadź odpowiednie zmiany i wybierz pozycję Utwórz.

    Plan usługi App Service reprezentuje kolekcję zasobów fizycznych użytych do obsługi aplikacji w ramach subskrypcji platformy Azure. Dowiedz się więcej o usłudze App Service.

    Tworzenie usługi App Service.

    Ustawienie Sugerowana wartość opis
    Konto służbowe lub szkolne platformy Azure albo osobiste konto Microsoft your-user-account Wybierz konto użytkownika.
    Nazwa aplikacji sieci Web custom-web-api-app-name lub nazwa domyślna Wprowadź nazwę aplikacji interfejsu API sieci Web, która jest używana w adresie URL aplikacji, na przykład: http://web-api-app-name.
    Subskrypcja Azure-subscription-name Wybierz subskrypcję platformy Azure, której chcesz użyć.
    Grupa zasobów Azure-resource-group-name Wybierz istniejącą grupę zasobów Azure lub, jeśli jeszcze tego nie zrobiono, utwórz grupę zasobów.

    Uwaga: Grupa zasobów Azure służy do porządkowania zasobów Azure w ramach subskrypcji Azure.

    Plan usługi App Service App-Service-plan-name Wybierz istniejący plan usługi App Service lub, jeśli jeszcze tego nie zrobiono, utwórz plan.

    Jeśli tworzysz plan usługi aplikacji, określ następujące elementy.

    Ustawienie Sugerowana wartość opis
    Location deployment-region Wybierz region wdrożenia aplikacji.
    Rozmiar App-Service-plan-size Wybierz rozmiar Twojego planu określający koszt i wydajność zasobów obliczeniowych dla planu usług.

    Aby skonfigurować inne zasoby wymagane przez aplikację, wybierz pozycję Poznaj dodatkowe usługi Azure.

    Ustawienie Sugerowana wartość Opis
    Typ zasobu Azure-resource-type Wybierz i skonfiguruj dodatkowe zasoby wymagane przez aplikację.
  6. Po wdrożeniu projektu przez Visual Studio utwórz dla niego kod aplikacji.

Utwórz plik OpenAPI (Swagger), który opisuje twoje Web API

Do połączenia aplikacji internetowego interfejsu API z usługą Power Automate, Power Apps lub Logic Apps jest potrzebny plik OpenAPI (dawniej Swagger) opisujący operacje interfejsu API. Możesz napisać własną definicję OpenAPI dla swojego API za pomocą edytora online Swagger, ale ten samouczek używa narzędzia open source o nazwie Swashbuckle.

  1. Jeśli jeszcze tego nie zrobiono, należy zainstalować pakiet Swashbuckle Nuget w projekcie Visual Studio:

    1. W Visual Studio wybierz Narzędzia > NuGet Menedżer pakietów > Konsola menedżera pakietów.

    2. W konsoli Konsola menedżera pakietów przejdź do swojego katalogu aplikacji projektu, jeśli jeszcze tego nie zrobiono (uruchom Set-Location "project-path"), i uruchom to polecenie cmdlet PowerShell:

      Install-Package Swashbuckle

      Zrzut ekranu przedstawiający zainstalowany przy użyciu konsoli Menedżera pakietów.

    Porada

    Jeśli uruchomisz swoją aplikację po zainstalowaniu Swashbuckle, Swashbuckle wygeneruje plik OpenAPI pod tym adresem:

      http://{your-web-api-app-root-URL}/swagger/docs/v1

    Swashbuckle generuje również interfejs użytkownika pod tym adresem URL:

      http://{your-web-api-app-root-URL}/swagger

  2. Gdy będziesz gotowy, opublikuj aplikację interfejsu API sieci Web w Azure. Aby opublikować publikację z poziomu Visual Studio, należy kliknąć prawym przyciskiem myszy projekt sieci Web w Eksploratorze rozwiązań, a następnie wybrać polecenie Opublikuj i postępować zgodnie z instrukcjami wyświetlanymi na ekranie.

    Ważne

    Jeśli dokument OpenAPI zawiera zduplikowane identyfikatory operacji, będzie nieprawidłowy. Przykładowy szablon języka C# powtarza identyfikator operacji, Values_Get.

    Jeśli został użyty przykładowy szablon języka C# można rozwiązać ten problem Value_Get, zmieniając jedno wystąpienie identyfikatora operacji na i ponownie opublikować.

  3. Pobierz dokument OpenAPI, przechodząc do tej lokalizacji:

    http://{your-web-api-app-root-URL}/swagger/docs/v1

    Możesz również pobrać przykładowy dokument OpenAPI z tego samouczka. Przed przystąpieniem do korzystania z dokumentu należy się upewnić, że w programie usunięto komentarze, które zaczynają się od //.

  4. Zapisz zawartość pliku w formacie JSON. W zależności od przeglądarki może być konieczne skopiowanie i wklejenie tekstu do pustego pliku tekstowego.

Konfigurowanie uwierzytelniania tożsamością Microsoft Entra

Teraz utworzymy dwa zastosowania tożsamości Microsoft Entra w systemie Azure. Więcej informacji można uzyskać w artykule Integracja aplikacji z tożsamością Microsoft Entra .

Ważne

Obie aplikacje muszą znajdować się w tym samym katalogu.

Pierwsze zastosowanie tożsamości Microsoft Entra: zabezpieczanie internetowego interfejsu API

Pierwsza aplikacja tożsamości Microsoft Entra służy do zabezpieczania internetowego interfejsu API. Nadaj jej nazwę webAPI. W celu włączenia uwierzytelniania tożsamością Microsoft Entra w internetowym interfejsie API należy wykonać następujące kroki przy użyciu następujących wartości:

  • Adres URL logowania: https://login.windows.net
  • Adres URL odpowiedzi: https://<your-root-url>/.auth/login/aad/callback
  • Nie potrzebujesz klucza klienta.
  • Nie musisz delegować żadnych uprawnień.
  • Skopiuj identyfikator aplikacji, ponieważ później jest potrzebny.

Druga aplikacja tożsamości Microsoft Entra: zabezpieczanie niestandardowego łącznika i delegowanego dostępu

Druga aplikacja tożsamości Microsoft Entra służy do zabezpieczania rejestracji łącznika niestandardowego i uzyskiwania delegowanego dostępu do internetowego interfejsu API chronionego przez pierwszą aplikację. Nadaj tej aplikacji nazwę webAPI-customAPI.

  • Adres URL logowania: https://login.windows.net
  • Adres URL odpowiedzi: https://msmanaged-na.consent.azure-apim.net/redirect
  • Dodaj uprawnienia, aby mieć delegowany dostęp do internetowego interfejsu API.
  • Skopiuj identyfikator aplikacji, ponieważ później jest potrzebny.
  • W tym celu należy wygenerować klucz klienta i skopiować go, ponieważ jest on potrzebny później.

Dodawanie uwierzytelniania do aplikacji internetowej platformy Azure

  1. Zaloguj się do witryny Azure Portal, a następnie znajdź aplikację sieci Web, która została wdrożona w pierwszej części.

  2. Wybierz Ustawienia, a następnie pozycję Uwierzytelnianie/autoryzacja.

  3. Włączy Uwierzytelnianie usługi App Service, a następnie wybierz Azure Active Directory. W następnym bloku wybierz pozycję Express.

  4. Kliknij pozycję Wybierz istniejącą aplikację usługi AD i wybierz wcześniej utworzoną aplikację webAPI tożsamości Microsoft Entra.

Teraz powinno być możliwe używanie tożsamości Microsoft Entra do uwierzytelniania aplikacji internetowej użytkownika.

Dodawanie niestandardowego łącznika do usługi Power Automate

  1. Zmodyfikuj dokument OpenAPI, aby dodać obiekt securityDefintions i uwierzytelnianie w usłudze tożsamości Microsoft Entra używane w aplikacji internetowej. Sekcja pliku OpenAPI z właściwością host powinna wyglądać następująco:
// File header should be above here...

"host": "<your-root-url>",
"schemes": [
    "https"      //Make sure this is https!
],
"securityDefinitions": {
    "Microsoft Entra ID": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
        "tokenUrl" : "https://login.windows.net/common/oauth2/token",
        "scopes": {}
    }
},

// The rest of the OpenAPI follows...
  1. Przejdź do usługi Power Automate i dodaj niestandardowy łącznik zgodnie z opisem w temacie Używanie łączników niestandardowych w usłudze Power Automate.

  2. Po przesłaniu dokumentu OpenAPI kreator automatycznie wykrywa, że w internetowym interfejsie API stosowane jest uwierzytelnianie tożsamością Microsoft Entra.

  3. Skonfiguruj uwierzytelnianie w usłudze tożsamości Microsoft Entra dla łącznika niestandardowego.

  • Identyfikator klienta: Identyfikator klienta aplikacji webAPI-CustomAPI
  • Klucz tajny: Klucz klienta aplikacji webAPI-CustomAPI
  • Adres URL logowania: https://login.windows.net
  • Identyfikator URI zasobu: Identyfikator klienta aplikacji webAPI
  1. Wybierz pozycję Utwórz, aby utworzyć połączenie z łącznikiem niestandardowym.

Zobacz też

Dowiedz się więcej o uwierzytelnianiu w usłudze tożsamości Microsoft Entra

Przekazywanie opinii

Jesteśmy wdzięczni za opinie na temat problemów z platformą łączników oraz pomysły na nowe funkcje. Aby przekazać opinię, przejdź na stronę Przesyłanie problemów lub uzyskiwanie pomocy dotyczącej łączników i wybierz typ opinii.