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 temat należy utworzyć łącznik niestandardowy od podstaw, OpenAPI bez konieczności używania definicji do opisywania operacji interfejsu API analizy tekstu usług Azure Cognitive Services (przykład dla tej serii). Zamiast tego program opisuje całkowicie łącznik w Kreatorze łącznika niestandardowego.

Aby opisać interfejs API, przejdź do Tworzenie łącznika niestandardowego od definicji OpenAPI.

Uwaga

Obecnie można utworzyć łącznik niestandardowy od początku w Power Automate i Power Apps. Dla Logic Apps należy uruchomić co najmniej jedną podstawową definicję OpenAPI.

Wymagania wstępne

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

• Jedna z następujących subskrypcji:

  • Power Automate
  • Power Apps

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.

   

   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.

   

   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.

   Porada

   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.

   

   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.

   

   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.

   

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.

     

   • (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.

   

(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:

• Przepływu
• Aplikacji
• Aplikacji logiki

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

• Udostępnij łącznik
• Zatwierdź swój łącznik

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.