Tworzenie łącznika niestandardowego na podstawie definicji interfejsu OpenAPI

  • Artykuł

Uwaga

Ten temat jest częścią serii samouczków dotyczących tworzenia i używania łączników niestandardowych w usługach Azure Logic Apps, Microsoft Power Automate i Microsoft Power Apps. Należy zapoznać się z omówieniem łączników niestandardowych w celu zrozumienia procesu.

Aby utworzyć łącznik niestandardowy, należy opisać interfejs API, z którym chcesz nawiązać połączenie, aby łącznik rozumiał struktury danych i operacje interfejsu API. W tym temacie utworzysz niestandardowy łącznik, używając definicji OpenAPI, która opisuje Cognitive Services – Text Analytics Sentiment API (nasz przykład dla tej serii).

Inne sposoby opisywania API znajdziesz w następujących tematach:

Wymagania wstępne

  • Definicja OpenAPI opisuje przykładowy interfejs API. Podczas tworzenia niestandardowego łącznik definicja OpenAPI musi być mniejsza niż 1 MB. Definicja OpenAPI musi być w formacie OpenAPI 2.0 (dawniej znanym jako Swagger).

    Jeśli istnieje wiele definicji bezpieczeństwa, łącznik niestandardowy wybiera najwyższą definicję bezpieczeństwa. Tworzenie niestandardowego łącznika nie obsługuje poświadczeń klienta (na przykład aplikacji i hasła) w definicji bezpieczeństwa OAuth.

  • Klucz interfejsu API dla interfejsu API analizy tekstu usług Cognitive Services.

  • Jedna z następujących subskrypcji:

  • Jeśli używasz usługi Logic Apps, najpierw utwórz łącznik niestandardowy usługi Azure Logic Apps.

Importuj definicję OpenAPI

Jesteś teraz gotowy do pracy z definicją OpenAPI, którą pobrałeś. Definicja zawiera wszystkie wymagane informacje i można przejrzeć te informacje i zaktualizować je po przejściu do kreatora łączników niestandardowych.

Zacznij od zaimportowania definicji interfejsu OpenAPI dla usługi Logic Apps lub Power Automate i Power Apps.

Uwaga

Definicja OpenAPI musi być w formacie OpenAPI 2.0 (dawniej znanym jako Swagger). Definicje OpenAPI w formacie OpenAPI 3.0 nie są obsługiwane.

Import definicji OpenAPI dla Logic Apps

  1. Przejdź do witryny Azure Portal i otwórz łącznik usługi Logic Apps utworzony wcześniej w procedurze Tworzenie łącznika niestandardowego usługi Azure Logic Apps.

  2. W menu swojego łącznika wybierz kolejno pozycje Łącznik usługi Logic Apps i wybierz Edytuj.

    Edytuj łącznik usługi Logic Apps.

  3. W obszarze Ogólne wybierz opcję Przekaż plik OpenAPI, a następnie przejdź do utworzonej definicji interfejsu OpenAPI.

    Przekaż plik OpenAPI.

Uwaga

W tym samouczku nałożono interfejs API REST, ale można również używać interfejsu API SOAP z usługą Logic Apps.

Zaimportuj definicję OpenAPI dla Power Automate i Power Apps

  1. Przejdź do obszaru make.powerapps.com lub flow.microsoft.com.

  2. W lewym okienku wybrać Dane > Łączniki niestandardowe.

    Wybieranie łącznika niestandardowego.

  3. Wybierz pozycję Nowy łącznik niestandardowy, a następnie Importuj plik OpenAPI.

    Importuj plik OpenAPI.

  4. Wprowadź nazwę łącznika niestandardowego, a następnie przejdź do utworzonej lub pobranej definicji OpenAPI i wybierz pozycję Kontynuuj.

    Przekaż kolekcję Postman.

    Parametr Wartość
    Tytuł łącznika niestandardowego SentimentDemo

Przejrzyj szczegóły ogólne

Od tej pory prezentowany będzie interfejs użytkownika usługi Power Automate, ale kroki są w dużym stopniu takie same dla wszystkich trzech technologii. Będziemy wskazywać wszelkie różnice. W tej części tematu zajmiemy się głównie interfejsem użytkownika i pokażemy, jak poszczególne wartości odpowiadają sekcjom pliku OpenAPI.

  1. Upewnij się, że w górnej części kreatora ustawiono nazwę SentimentDemo, a następnie wybierz pozycję Utwórz łącznik.

  2. Na stronie Ogólne przejrzyj informacje zaimportowane z definicji OpenAPI, w tym dane hosta API i podstawowy adres URL dla interfejsu API. Łącznik używa hosta interfejsu API i podstawowego adresu URL do określania sposobu wywoływania interfejsu API.

    Strona ogólna łącznika niestandardowego.

    Uwaga

    Aby uzyskać więcej informacji na temat łączenia się z lokalnymi interfejsami API, zobacz Łączenie się z lokalnymi interfejsami API przy użyciu bramy danych.

    Poniższa sekcja definicji OpenAPI zawiera informacje dotyczące tej strony interfejsu użytkownika:

      "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ]

Przejrzyj typ uwierzytelniania

W przypadku łączników niestandardowych dostępnych jest kilka opcji uwierzytelniania. Interfejsy API Cognitive Services używają uwierzytelniania kluczem API, więc to właśnie jest określone w definicji OpenAPI.

Na stronie Zabezpieczenia przejrzyj informacje dotyczące uwierzytelniania dla klucza interfejsu API.

Parametry klucza interfejsu API.

Etykieta jest wyświetlana w momencie, gdy pracownik w pierwszej kolejności nawiązuje połączenie z łącznikiem niestandardowym; możesz wybrać Edytuj i zmienić tę wartość. Lokalizacja i nazwa parametru musi odpowiadać oczekiwaniom związanym z interfejsem API, w tym przypadku Ocp-Apim-Subscription-Key i Nagłówka.

Poniższa sekcja definicji OpenAPI zawiera informacje dotyczące tej strony interfejsu użytkownika:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Zapoznanie się z definicją łącznika

Strona Definicja kreatora niestandardowych łączników daje wiele możliwości zdefiniowania sposobu działania łączników oraz jego ekspozycji w aplikacjach logicznych, przepływach i aplikacjach. Wyjaśnimy interfejs użytkownika i omówimy kilka opcji w tej sekcji, ale zachęcamy również do samodzielnego odkrywania. Aby uzyskać informacje na temat definiowania obiektów od podstaw w tym interfejsie użytkownika, zobacz Tworzenie definicji łącznika.

  1. W następującym obszarze są wyświetlane wszystkie akcje, wyzwalacze (dla usług Logic Apps i Power Automate) oraz odwołania zdefiniowane dla łącznika. W tym przypadku wyświetlana jest akcja DetectSentiment z definicji OpenAPI. Ten łącznik nie ma żadnych wyzwalaczy, ale możesz dowiedzieć się więcej o wyzwalaczach dla łączników niestandardowych w artykule Używanie elementów webhook z usługami Azure Logic Apps i Power Automate.

    Strona definicja — akcje i wyzwalacze.

  2. W obszarze Ogólne wyświetlane są informacje o aktualnie wybranym wyzwalaczu lub akcji. W tym miejscu można edytować informacje, w tym właściwość Widoczność operacji i parametrów w aplikacji logiki lub przepływie:

    • brak: zazwyczaj wyświetlane w aplikacji logiki lub przepływie

    • zaawansowane: ukryte w dodatkowym menu

    • wewnętrzne: ukryte przed użytkownikiem

    • ważne: zawsze wyświetlane użytkownikowi w pierwszej kolejności

      Strona Definicja — ogólne.

  3. Obszar Żądanie wyświetla informacje oparte na żądaniu HTTP, które jest zawarte w definicji OpenAPI. W tym przypadku widać, że czasownik HTTP jest ustawiony jako OPUBLIKUJ, a adres URL to /text/analytics/v2.0/sentiment (Pełen adres URL do interfejsu API to <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Wkrótce przyjrzymy się parametrowi treści.

    Strona Definicja — żądanie.

    Poniższa część definicji OpenAPI zawiera informacje dla obszarów Ogólne i Żądanie interfejsu użytkownika:

    "paths": {
  "/text/analytics/v2.0/sentiment": {
    "post": {
      "summary": "Returns a numeric score representing the sentiment detected",
      "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
      "operationId": "DetectSentiment"

  4. Obszar Odpowiedź wyświetla informacje oparte na odpowiedzi HTTP, które jest zawarte w definicji OpenAPI. W naszym przypadku jedyna zdefiniowana odpowiedź to 200 (odpowiedź oznaczająca powodzenie), ale można zdefiniować dodatkowe odpowiedzi.

    Strona Definicja — odpowiedź.

    Poniższa sekcja definicji OpenAPI zawiera niektóre informacje związane z odpowiedzią:

    "score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}

    W tej sekcji przedstawiono dwie wartości zwracane przez łącznik: id i score. Zawiera ich typy danych oraz pole x-ms-summary, które jest rozszerzeniem OpenAPI. Aby uzyskać więcej informacji na temat tego i innych rozszerzeń, zobacz Rozszerzenie definicji OpenAPI dla niestandardowego łącznika.

  5. W obszarze Sprawdzanie poprawności są wyświetlane wszelkie problemy wykryte w definicji interfejsu API. Pamiętaj o sprawdzeniu tego obszaru przed zapisaniem łącznika.

    Definicja — walidacja.

Aktualizowanie definicji

Definicja OpenAPI, którą pobrałeś, jest dobrym podstawowym przykładem, ale możesz pracować z definicjami, które wymagają wielu aktualizacji, aby łącznik był bardziej przyjazny, gdy ktoś używa go w aplikacji logicznej, przepływie lub aplikacji. Pokażemy, jak wprowadzić zmianę definicji.

  1. W obszarze Żądanie wybierz pozycję treść, a następnie pozycję Edytuj.

    Edytuj żądanie treści.

  2. W obszarze Parametr są teraz wyświetlane trzy parametry, których oczekuje interfejs API: ID, Language i Text. Zaznacz Identyfikator, a następnie wybierz Edytuj.

    Edytuj żądanie identyfikatora treści.

  3. W obszarze Właściwości schematu zaktualizuj opis dla parametru, a następnie wybierz pozycję Wstecz.

    Edytuj właściwość schematu.

    Parametr Wartość
    opis Identyfikator liczbowy każdego przesyłanego dokumentu

  4. W obszarze Parametr wybierz pozycję Wstecz, aby wrócić do strony głównej definicji.

  5. W prawym górnym rogu kreatora wybierz Aktualizuj łącznik.

Pobierz zaktualizowany plik OpenAPI

Łącznik niestandardowy można utworzyć przy użyciu pliku OpenAPI lub kolekcji Postman albo od podstaw (w usługach Power Automate i Power Apps). Bez względu na sposób tworzenia łącznika można pobrać definicję interfejsu OpenAPI, której usługa używa wewnętrznie.

  • W usłudze Logic Apps pobierz z łącznika niestandardowego.

    Pobierz definicję OpenAPI w Logic Apps.

  • W Power Automate lub Power Apps pobierz z listy łączników niestandardowych.

    Pobierz definicję OpenAPI w Power Automate.

Testowanie łącznika

Teraz, po utworzeniu łącznika, przetestuj go, aby upewnić się, że działa prawidłowo. Testowanie jest obecnie dostępne tylko w Power Automate i Power Apps.

Ważne

W przypadku korzystania z klucza interfejsu API zaleca się, aby łącznik nie był testowany od razu po jego utworzeniu. Zanim łącznik będzie gotowy do podłączenia do interfejsu API, może zająć kilka minut.

  1. Na stronie Test wybierz pozycję Nowe połączenie.

    Nowe połączenie.

  2. Wprowadź klucz interfejsu API z interfejsu API analizy tekstu, a następnie wybierz pozycję Utwórz połączenie.

    Utwórz połączenie.

  3. Powróć do strony Test i wykonaj jedną z następujących czynności:

    • W usłudze Power Automate nastąpi przekierowanie do strony Testuj. Wybierz ikonę odświeżania, aby upewnić się, że informacje o połączeniu zostały zaktualizowane.

      Odświeżanie połączenia.

    • W usłudze Power Apps nastąpi przekierowanie do listy połączeń dostępnych w bieżącym środowisku. W prawym górnym rogu, wybierz ikonę zębatki, a następnie wybierz Łączniki niestandardowe. Wybierz utworzony łącznik, a następnie wróć do strony Testuj.

      Ikona koła zębatego w usłudze.

  4. Na stronie Testuj wprowadź wartość w polu tekst (w pozostałych polach będą używane ustawione wcześniej wartości domyślne), a następnie wybierz pozycję Testuj operację.

    Testowanie operacji.

  5. Łącznik wywołuje interfejs API i umożliwia przejrzenie odpowiedzi, która zawiera wynik opinii.

    Odpowiedź łącznika.

Następne kroki

Teraz, po utworzeniu łącznika niestandardowego i zdefiniowaniu jego zachowań, możesz go użyć.

Możesz także udostępnić łącznik w organizacji lub uzyskać dla niego certyfikat, aby mogły go używać osoby spoza organizacji.

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.