Tworzenie łącznika niestandardowego od podstaw

Ten artykuł 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.

Uwaga

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 stworzysz niestandardowy łącznik od podstaw, nie używając kolekcji Postman ani definicji OpenAPI do opisania Azure Cognitive Services Text Analytics operacji zbierania opinii API (nasz przykład dla tej serii). Zamiast tego program opisuje całkowicie łącznik w Kreatorze łącznika niestandardowego.

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

Uwaga

Obecnie można utworzyć łącznik niestandardowy od początku w Power Automate i Power Apps. W przypadku Logic Apps musisz zacząć przynajmniej od podstawowej definicji OpenAPI lub kolekcji Postman.

Wymagania wstępne

Uruchamianie Kreatora łącznika niestandardowego

  1. Zaloguj się w Power Apps lub Power Automate.

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

  3. Wybierz Nowy niestandardowy łącznik > Utwórz z pustego.

  4. Wprowadź nazwę łącznika niestandardowego, a następnie wybierz pozycję Kontynuuj.

    Parametr Wartość
    Tytuł łącznika niestandardowego SentimentDemo

Krok 1. Aktualizowanie ogólnych szczegółów

Od tej pory prezentowany będzie interfejs użytkownika usługi Power Automate, ale kroki są w dużym stopniu takie same dla wszystkich technologii. Będziemy wskazywać wszelkie różnice.

Na karcie Ogólne można wykonać następujące czynności:

  1. W polu Opis wprowadź znaczącą wartość. Ten opis pojawi się w szczegółach łącznika niestandardowego i może pomóc innym zdecydować, czy łącznik może być dla nich przydatny.

  2. Zaktualizuj pole Host do adresu dla API analizy tekstu. Łącznik używa hosta interfejsu API i podstawowego adresu URL do określania sposobu wywoływania interfejsu API.

    Parametr Wartość
    opis Korzystając z interfejsu API analizy tonacji tekstu usług Cognitive Services, określa, czy tekst jest pozytywny, czy negatywny
    Gospodarz westus.api.cognitive.microsoft.com

Krok 2. Określanie typu uwierzytelniania

W przypadku łączników niestandardowych dostępnych jest kilka opcji uwierzytelniania. Interfejsy API usługi Cognitive Services korzystają z uwierzytelniania za pomocą klucza interfejsu API, który określiłeś dla tego samouczka.

  1. Na karcie Zabezpieczenia w obszarze Typ uwierzytelniania wybierz opcję Klucz interfejsu API.

  2. W obszarze Klucz interfejsu API określ etykietę parametru, nazwę i lokalizację. Wybierz zrozumiałą etykietę, która będzie wyświetlana, gdy użytkownik nawiąże po raz pierwszy połączenie z łącznikiem niestandardowym. Nazwa parametru i lokalizacja muszą być takie same, jak w przypadku oczekiwań interfejsów API. Wybierz pozycję Połącz.

    Parametr Wartość
    Etykieta parametru Klucz interfejsu API
    Nazwa parametru Ocp-Apim-Subscription-Key
    Lokalizacja parametru Nagłówek
  3. Upewnij się, że w górnej części kreatora ustawiono nazwę SentimentDemo, a następnie wybierz pozycję Utwórz łącznik.

Krok 3. Tworzenie definicji łącznika

Kreator łącznika niestandardowego udostępnia wiele opcji definiowania sposobu działania łącznika oraz sposobu jego eksponowania w aplikacjach logiki, 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.

Tworzenie akcji

Pierwsza rzecz do wykonania polega na utworzeniu akcji, która wywołuje operację interfejsu API analizy tekstów opinii.

  1. W oknie Definicja obszar po lewej stronie zawiera wszystkie akcje, wyzwalacze (dla usługi Logic Apps i Power Automate) oraz odwołania zdefiniowane dla łącznika. Wybierz Nowa akcja

    W tym łączniku nie ma wyzwalaczy. Aby dowiedzieć się o wyzwalaczach dla niestandardowych łączników, przejdź do Używaj webhooków z Azure Logic Apps i Power Automate.

  2. W obszarze Ogólne wyświetlane są informacje o aktualnie wybranym wyzwalaczu lub akcji. Dodaj podsumowanie, opis i identyfikator operacji dla tej akcji.

    Parametr Wartość
    Podsumowanie Zwraca wartość liczbową reprezentującą wykrytą opinię
    opis Interfejs API zwraca wynik liczbowy z zakresu od 0 do 1. Wyniki zbliżone do wartości 1 wskazują na pozytywną tonację, a wyniki zbliżone do wartości 0 wskazują na negatywną tonację.
    Identyfikator operacji DetectSentiment

    Właściwość Widoczność pozostaw ustawioną na wartość brak. Ta właściwość dla operacji i parametrów w aplikacji lub przepływie logicznym ma następujące opcje:

    • brak: zazwyczaj wyświetlane w aplikacji logiki lub przepływie
    • zaawansowane: ukryte pod innym menu
    • wewnętrzne: ukryte przed użytkownikiem
    • ważne: zawsze wyświetlane użytkownikowi w pierwszej kolejności
  3. W obszarze Żądania są wyświetlane informacje na podstawie żądania HTTP dotyczącego akcji. Wybierz opcję Importuj z próbki.

  4. Podaj informacje niezbędne do nawiązania połączenia z interfejsem API, określ treść żądania (podaną za poniższym obrazem), a następnie wybierz Importuj. Udostępniamy te informacje za Ciebie, ale w przypadku publicznego interfejsu API zazwyczaj uzyskujesz te informacje z dokumentacji, jak w Interfejs API analizy tekstu (v2.0).

    Parametr Wartość
    Czasownik POST
    URL <https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
    Body Użyj następującego kodu JSON

    Przykład:

    {
      "documents": [
        {
          "language": "string",
          "id": "string",
          "text": "string"
        }
      ]
    }
    
  5. W obszarze Odpowiedź są wyświetlane informacje na podstawie odpowiedzi HTTP dotyczącego akcji. Wybierz pozycję Dodaj odpowiedź domyślną.

  6. Określ treść odpowiedzi, a następnie wybierz Importuj. Podobnie jak w przypadku treści żądania, udostępniamy te informacje za obrazem, ale zazwyczaj są one dostępne w dokumentacji interfejsu API.

    Przykład:

    {
     "documents": [
       {
         "score": 0.0,
         "id": "string"
       }
     ],
     "errors": [
       {
         "id": "string",
         "message": "string"
       }
     ]
    }
    
  7. W obszarze Sprawdzanie poprawności są wyświetlane wszelkie problemy wykryte w definicji interfejsu API. Sprawdź stan, a następnie w prawym górnym rogu kreatora wybierz Aktualizuj łącznik.

Aktualizowanie definicji

Teraz zmieńmy kilka elementów tak, aby łącznik był bardziej przyjazny, gdy ktoś użyje go w aplikacji logiki, przepływie lub zwykłej aplikacji.

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

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

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

    Parametr Wartość
    Nazwa ID
    opis Identyfikator każdego przesyłanego dokumentu
    Domyślna wartość 1
    Wymagany Tak
  4. W obszarze Parametr wybierz Język > Edycja, a następnie powtórz proces, którego użyłeś dla id w krokach 2 i 3 tej procedury, z następującymi wartościami.

    Parametr Wartość
    Nazwa Język
    opis Dwu- lub czteroznakowy kod językowy dla tekstu
    Domyślna wartość en
    Wymagany Tak
  5. W obszarze Parametr wybierz Tekst > Edycja, a następnie powtórz proces, którego użyłeś dla id w krokach 2 i 3 tej procedury, z następującymi wartościami.

    Parametr Wartość
    Nazwa Tekst
    Opis Tekst do przeanalizowania pod kątem tonacji
    Domyślna wartość Brak
    Wymagany Tak
  6. W obszarze Parametr wybierz pozycję Wstecz, aby wrócić do głównej karty Definicja.

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

Krok 4. (Opcjonalnie) Włączanie łącznika jako wtyczki AI

Użyj karty Wtyczka AI (wersja zapoznawcza) dla łącznika tylko wtedy, gdy planujesz certyfikować swój łącznik. Aby łącznik mógł służyć jako wtyczka AI, musi mieć certyfikat.

Zanim włączysz łącznik jako wtyczkę AI, upewnij się, że rozumiesz przypadek użycia scenariuszy wtyczek AI i znasz inne kwestie, takie jak możliwość obsługi, najlepsze praktyki i zalecenia. Więcej informacji: Tworzenie łącznika plug-in AI (wersja zapoznawcza)

  1. W okienku nawigacji po lewej stronie wybierz pozycję Łączniki niestandardowe.

    Jeśli nie widzisz pozycji Łączniki niestandardowe, wybierz Więcej > Odkryj wszystko > Łączniki niestandardowe. Opcja pojawi się w lewym panelu nawigacyjnym.

  2. W prawym górnym rogu wybierz opcję z menu Nowy łącznik niestandardowy.

  3. Upewnij się, że wykonano Krok 1, Krok 2 i Krok 3 w tym artykule.

  4. Wybierz kartę Wtyczka AI (wersja zapoznawcza).

  5. W sekcji Manifest wtyczki wprowadź szczegóły, aby włączyć ten łącznik jako wtyczkę AI.

    Zrzut ekranu przedstawiający pola na stronie „Manifest wtyczki”.

    Pole Popis
    Manifest wtyczki: nazwa Nazwa wtyczki AI.
    Manifest wtyczki: opis Opis wtyczki AI. Więcej informacji: Tworzenie łącznika plug-in AI (wersja zapoznawcza)
    Manifest wtyczki: kontaktowy adres e-mail Adres e-mail osoby kontaktowej dla tej wtyczki AI.
    Manifest wtyczki: adres URL informacji prawnych Publicznie dostępna lokalizacja, w której publikowane są informacje prawne dotyczące wtyczki AI.
  6. Przewiń w dół do sekcji Szczegóły akcji wtyczki i wprowadź szczegóły akcji dla każdej akcji we wtyczce AI łącznika.

    Zrzut ekranu przedstawiający pola na stronie „Szczegóły akcji wtyczki”.

    Pole Popis
    Szczegóły akcji wtyczki: podsumowanie Podsumowanie każdej akcji wtyczki AI, którą mogą wykonać użytkownicy.
    Szczegóły akcji wtyczki: opis Opis każdej akcji, którą użytkownicy mogą wykonać w odniesieniu do tego konkretnego kroku akcji wtyczki AI.
    Pole wyboru: Włącz jako operację wtyczki plug-in pomocnika Gdy w polu wyboru znajduje się znacznik wyboru, operacja wtyczki AI jest włączona.
    Pole wyboru: Wymagane potwierdzenie użytkownika? Jeśli w polu wyboru znajduje się znacznik wyboru, wymagane jest potwierdzenie przez użytkownika.

    Napiwek

    Jeśli potrzebujesz pomocy w określeniu swoich działań, włącz przełącznik Edytor Swagger.

  7. Przewiń w dół do sekcji Parametr i wprowadź szczegóły parametrów wtyczki AI łącznika.

    Zrzut ekranu przedstawiający pola na stronie „Parametry”.

    Pole Popis
    Parametr: nazwa Nazwa parametru. Używaj nazw umożliwiających identyfikację, takich jak Identyfikator konta zamiast ID.
    Parametr: opis Opis parametru. Użyj opisowego wyjaśnienia, takiego jak Data urodzenia kontaktu w formacie DD/MM/RRRR zamiast d_urodzin. Takie nazwy i opisy pomagają LLM (dużym modelom językowym) skutecznie współdziałać z wtyczką AI.
    Parametr: podsumowanie Zbiorcze informacje o parametrze.
    Parametr: wartość domyślna Wartość domyślna parametru.
  8. W sekcji Żądanie poniżej sekcji Wtyczka AI (wersja zapoznawcza) wybierz parametr wejściowy, a następnie wprowadź opis.

Krok 5: (opcjonalnie) Użyj niestandardowej pomocy technicznej do kodu

Niestandardowy kod przekształca żądania i odpowiedzi poza zakresem istniejących szablonów polityki. Przekształcenia obejmują wysyłanie zewnętrznych żądań w celu pobrania dodatkowych danych. Gdy używany jest kod, będzie on miał pierwszeństwo przed definicją bezkodową. Oznacza to, że kod zostanie wykonany, a my nie wyślemy żądania do zaplecza.

Uwaga

  • To krok jest opcjonalny. Sposób tworzenia łącznika można zakończyć, ignorując ten krok i przechodząc do kroku 6: Przetestuj łącznik.
  • Obsługa kodu niestandardowego jest dostępna w publicznej wersji zapoznawczej.

Możesz wkleić swój kod lub przesłać plik ze swoim kodem. Twój kod musi:

  • Zostanie wpisany w języku C#.
  • Maksymalny czas wykonania to pięć sekund.
  • Rozmiar pliku nie większy niż 1 MB.

Instrukcje i przykłady pisania kodu można znaleźć w Pisanie kodu w łącznikach niestandardowych.

Często zadawane pytania dotyczące kodu niestandardowego można znaleźć w artykule Niestandardowy kod — często zadawane pytania.

  1. Na karcie Kod wstaw kod niestandardowy, używając jednej z następujących opcji:

    • Kopiuj/wklej
    • Wybierz przycisk Przekaż.

    Jeśli zdecydujesz się przesłać kod niestandardowy, dostępne będą tylko pliki z rozszerzeniem .cs lub .csx.

    Zrzut ekranu przedstawiający przekazywanie kodu niestandardowego.

    Ważne

    Obecnie obsługujemy tylko podświetlanie składni w edytorze kodu. Należy przetestować kod lokalnie.

  2. Po wklejeniu lub przesłaniu kodu wybierz przełączać się obok opcji Wyłączony kod, aby włączyć kod. Nazwa przełączana jest na Kod włączony.

    Kod można włączyć lub wyłączyć w dowolnym momencie. Jeśli przełączany jest Kod wyłączony, kod zostanie usunięty.

  3. Wybierz akcje i wyzwalacze, które chcesz zastosować do kodu niestandardowego, wybierając opcję z menu rozwijanego. Jeśli nie zostanie wybrana żadna operacja, akcje i wyzwalacze zostaną zastosowane do wszystkich operacji.

    Zrzut ekranu Wybierz akcje i wyzwalacze.

Krok 6. 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 karcie Test wybierz opcję Nowe połączenie.

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

    Uwaga

    W przypadku interfejsów API, które wymagają uwierzytelniania na okaziciela, dodaj Posiadacz i jedną spację przed kluczem API.

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

    • (W usłudze Power Automate) Nastąpi powrót na kartę Test. Aby zaktualizować informacje o połączeniu, wybierz ikonę odświeżania.

      Zrzut ekranu z Odśwież połączenie.

    • (W usłudze Power Apps) Nastąpi przekierowanie do listy połączeń dostępnych w bieżącym środowisku. W lewym okienku wybrać Dane > Łączniki niestandardowe. Wybierz utworzony łącznik, a następnie wróć na kartę Test.

  4. Na karcie Test wprowadź wartość pola tekstowego (inne pola korzystają z domyślnych ustawień ustawionych wcześniej), a następnie wybierz opcję Testuj operację.

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

    Zrzut ekranu odpowiedzi łącznika.

(Dla użytkowników interfejsu wiersza polecenia) Najlepsze praktyki

  • Pobierz wszystkie swoje łączniki i użyj Git lub dowolnego innego systemu zarządzania kodem źródłowym, aby zapisać pliki.

  • W przypadku niepoprawnej aktualizacji wdróż ponownie łącznik, ponownie uruchamiając polecenie update z poprawnym zestawem plików z systemu zarządzania kodem źródłowym.

  • Przetestuj łącznik niestandardowy i plik ustawień w środowisku testowym przed ich wdrożeniem w środowisku produkcyjnym.

  • Zawsze pamiętaj o sprawdzeniu, czy identyfikatory środowiska i łącznika są poprawne.

Następne kroki

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

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.