Tworzenie łącznika niestandardowego od podstaw

Aby utworzyć łącznik niestandardowy, należy zdefiniować interfejs API, z którym chcesz nawiązać połączenie, aby łącznik zrozumiał operacje i struktury danych interfejsu API. W tym artykule utworzysz łącznik niestandardowy od podstaw bez użycia formatu definicji interfejsu OpenAPI w celu opisania operacji analizy wydźwięku interfejsu API Azure Cognitive Services analiza tekstu (na przykład w tej serii). Zamiast tego program definiuje całkowicie łącznik w Kreatorze łącznika niestandardowego.

Aby poznać inny sposób opisywania interfejsu API, przejdź do Tworzenie łącznika niestandardowego na podstawie definicji OpenAPI.

Wymagania wstępne

• klucz API dla interfejsu analiza tekstu API usług Cognitive Services. Aby uzyskać klucz, utwórz zasób Język platformy Azure AI w portalu Azure. Ten krok wymaga subskrypcji Azure, a warstwa cenowa Bezpłatna F0 jest dostępna. Następnie skopiuj klucz ze strony Klucze i punkt końcowy zasobu.

  Notatka

  Interfejs API analizy tekstu w ramach usługi Azure Cognitive Services jest używany jako przykładowy interfejs API w tej serii samouczków. Jeśli masz problem z uzyskaniem klucza interfejsu API, nadal możesz wykonać kroki opisane w tym artykule przy użyciu dowolnego interfejsu API REST, do którego masz dostęp. Kreator łącznika niestandardowego akceptuje dowolny prawidłowy klucz API wymagany przez docelowy interfejs API.

• Jedna z następujących subskrypcji:

  • Power Automate - narzędzie do automatyzacji procesów
  • Power Apps

• Licencja na usługę Dataverse lub Dynamics 365 Customer Engagement oraz rola zabezpieczeń, która udziela uprawnień do tworzenia dla łączników. Potrzebujesz również dostępu do środowiska, w którym można utworzyć lub edytować rozwiązanie niezarządzane.

Uruchamianie Kreatora łącznika niestandardowego

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

2. W lewym okienku wybierz Rozwiązania.

3. Edytuj lub utwórz rozwiązanie niezarządzane dla łącznika niestandardowego. Dowiedz się, jak utworzyć rozwiązanie.

4. Wybierz pozycję Nowy>Automation>, a następnie wybierz pozycję Utwórz od podstaw.

5. Wprowadź nazwę łącznika, na przykład SentimentDemo. Wybierz Kontynuuj, aby otworzyć kreatora łączników i wypełnić pięć sekcji w Power Automate.

   • General

   • Zabezpieczenia

   • Definition

   • Kod (opcjonalnie)

   • Test

     

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

W sekcji Ogólne podaj informacje o łączniku, takie jak ikona, opis, schemat, host i podstawowy adres URL. Wykonaj te kroki:

1. Wybierz Prześlij ikonę łącznika lub Prześlij w oknie ikon, aby przesłać plik PNG lub JPG ikony łącznika. Upewnij się, że plik jest mniejszy niż 1 MB. Możesz również wybrać kolor tła ikony.

2. Wprowadź zrozumiałą wartość w polu Opis . Opis ten będzie wyświetlany w szczegółach łącznika niestandardowego i może ułatwić innym określenie, czy dany łącznik będzie dla nich przydatny.

3. Wybierz schemat adresu URL konektora: HTTPS lub HTTP.

4. 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

5. Zaktualizuj podstawowy adres URL— punkt początkowy dla wszystkich wywołań interfejsu API do określonej usługi.

6. Wybierz pozycję Zabezpieczenia w dolnej części, aby przejść do następnej sekcji.

Krok 2. Określanie typu uwierzytelniania

Łączniki niestandardowe oferują kilka opcji uwierzytelniania. Interfejsy API usług poznawczych używają uwierzytelniania przy użyciu klucza interfejsu API, dlatego określ ten typ dla tego samouczka.

1. W sekcji Zabezpieczenia w obszarze Typ uwierzytelniania wybierz pozycję Klucz interfejsu API z listy rozwijanej.

2. W obszarze Klucz interfejsu API określ etykietę parametru, nazwę i lokalizację. Wybierz zrozumiałą etykietę, ponieważ jest wyświetlana, gdy ktoś po raz pierwszy łączy się z łącznikiem niestandardowym. Nazwa parametru i jego lokalizacja muszą odpowiadać temu, czego oczekuje interfejs API.

   Parametr	Wartość
   Etykieta parametru	klucz interfejsu API
   Nazwa parametru	Ocp-Apim-Subscription-Key
   Lokalizacja parametru	Nagłówek

3. W górnej części kreatora upewnij się, że nazwa jest ustawiona na SentimentDemo, a następnie wybierz pozycję Utwórz łącznik.

4. Wybierz pozycję Definicja u dołu, aby przejść do następnej sekcji.

Krok 3. Tworzenie definicji łącznika

Kreator łącznika niestandardowego udostępnia wiele opcji opisywania sposobu działania łącznika i sposobu jego uwidocznienia w aplikacjach Logic Apps, przepływach, aplikacjach i agentach. Możesz zdefiniować akcje, wyzwalacze, odwołania i zasady. W tej sekcji opisano interfejs użytkownika i kilka opcji, ale warto również samodzielnie dalej eksplorować.

Tworzenie akcji

Utwórz akcję, która wywołuje operację analizy wydźwięku interfejsu API analiza tekstu. Na karcie Definicja w okienku po lewej stronie są wyświetlane wszystkie akcje, wyzwalacze (dla usług Logic Apps, Power Automate i Copilot Studio), odwołania i zasady zdefiniowane dla łącznika.

1. Wybierz Nowa akcja

2. W obszarze Ogólne 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 Żądanie wybierz pozycję Importuj z próbki.

4. Podaj informacje niezbędne do połączenia z interfejsem API, określ treść żądania (podana pod tabelą) i wybierz opcję Importuj.

   Zwykle te informacje można znaleźć w dokumentacji publicznego API.

   Parametr	Wartość
   Czasownik	POST
   adres URL	https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
   Treść	Użyj przykładowego kodu JSON.

   Przykład:

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. W obszarze Odpowiedź wybierz pozycję Dodaj odpowiedź domyślną.

6. Określ treść odpowiedzi, a następnie wybierz Importuj. Podobnie jak zrobiliśmy to w przypadku treści żądania, dostarczamy te informacje, ale zwykle są one podawane w dokumentacji interfejsu API.

   Przykład:

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

   W obszarze Sprawdzanie poprawności są wyświetlane wszelkie problemy wykryte w definicji interfejsu API.

7. Rozwiąż wszelkie problemy. Po pomyślnym zakończeniu walidacji definicji zostanie wyświetlony zielony znacznik wyboru.

8. W prawym górnym rogu kreatora wybierz pozycję Aktualizuj łącznik.

Aktualizowanie definicji

Zmieńmy kilka rzeczy, aby łącznik był bardziej przyjazny, gdy ktoś używa go w usłudze Logic Apps, Power Automate, Power Apps lub Copilot Studio.

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	identyfikator
   Opis	Identyfikator każdego przesyłanego dokumentu
   Domyślna wartość	1
   Jest wymagane	Tak

4. W obszarze Parametr wybierz pozycję język>Edytuj, a następnie powtórz proces, którego użyto powyżej dla id z następującymi wartościami language:

   Parametr	Wartość
   Nazwa	Język
   Opis	Dwu- lub czteroznakowy kod języka tekstu
   Domyślna wartość	en
   Jest wymagane	Tak

5. W obszarze Parametr wybierz pozycję tekst>Edytuj, a następnie powtórz proces, którego użyto powyżej dla id i language z następującymi wartościami text:

   Parametr	Wartość
   Nazwa	Tekst
   Opis	Tekst do przeanalizowania pod kątem tonacji
   Domyślna wartość	None
   Jest wymagane	Tak

6. W obszarze Parametr wybierz pozycję Wstecz, aby powrócić do głównej karty Definicja.

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

8. Wybierz Kod u dołu, aby przejść do kolejnej sekcji.

Krok 4: (Opcjonalnie) Użyj obsługi kodu niestandardowego

Niestandardowy kod przekształca ładunki żądań i odpowiedzi, wykraczając poza zakres istniejących szablonów zasad. Przekształcenia obejmują wysyłanie żądań zewnętrznych w celu pobrania większej ilości danych. Użycie kodu ma pierwszeństwo przed definicją bez kodu. Oznacza to, że kod jest wykonywany, a żądanie nie trafia do backendu.

Możesz wkleić kod lub przesłać plik z 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.

Aby uzyskać instrukcje i przykłady pisania kodu, zobacz Pisanie kodu w łącznikach niestandardowych.

Zobacz Często zadawane pytania dotyczące kodu niestandardowego.

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

   • Kopiowanie i wklejanie
   • Wybierz przycisk Przekaż.

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

   

   Ważne

   Obecnie edytor kodu obsługuje wyróżnianie składni tylko. Upewnij się, że przetestujesz swój kod lokalnie.

2. Po wklejeniu lub przesłaniu kodu wybierz przełącznik obok opcji Kod wyłączony, aby włączyć kod. Nazwa przełącznika zmienia się na Kod włączony.

   Kod można włączyć lub wyłączyć w dowolnym momencie. Jeśli przełącznik jest ustawiony na Kod wyłączony, Twój 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 wybierzesz operacji, akcje i wyzwalacze mają zastosowanie do wszystkich operacji.

   

Krok 5. Testowanie łącznika

Po utworzeniu łącznika przetestuj go, aby upewnić się, że działa prawidłowo. Obecnie łączniki można testować tylko w Power Automate i Power Apps.

1. Na karcie Test wybierz opcję Nowe połączenie.

2. Wprowadź klucz interfejsu API usługi analiza tekstu, a następnie wybierz Utwórz połączenie.

   Notatka

   W przypadku interfejsów API, które wymagają uwierzytelniania typu bearer, dodaj Bearer i jedną spację przed kluczem API.

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

   • (W Power Automate) Wrócisz do karty Test. Wybierz ikonę odświeżania, aby upewnić się, że informacje o połączeniu zostały zaktualizowane.

     

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

4. Na karcie Test wprowadź wartość dla pola text (użyj wartości domyślnych dla innych pól), a następnie wybierz Test operation.

   Łącznik wywołuje interfejs API.

5. Przejrzyj odpowiedź, która zawiera wynik opinii.

   

Najlepsze praktyki dla użytkowników CLI

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

Rozwiązywanie typowych problemów

• Akcje łącznika niestandardowego nie wczytują się: po utworzeniu lub zaktualizowaniu łącznika odczekaj kilka minut, aby platforma rozpropagowała zmiany, zanim rozpoczniesz testowanie. Wyczyść pamięć podręczną przeglądarki lub spróbuj wykonać prywatną sesję przeglądania, jeśli akcje nadal nie są wyświetlane.

• Błędy 401 Brak autoryzacji: Sprawdź, czy klucz interfejsu API lub poświadczenia protokołu OAuth są poprawne i nie wygasły. W przypadku łączników OAuth potwierdź, że adres URI przekierowania skonfigurowany u dostawcy tożsamości jest zgodny z adresem URI przekierowania dla danego łącznika, widocznym na karcie Zabezpieczenia.

• Błędy 403 Zabronione: sprawdź, czy punkt końcowy interfejsu API zezwala na połączenia z zakresów adresów IP platformy Power Platform. W przypadku usługi Azure Functions działającej za siecią wirtualną zapoznaj się z informacjami w sekcji Wychodzące adresy IP zarządzanych łączników i upewnij się, że reguły sieci zezwalają na ruch z tych zakresów adresów IP.

• Łącznik nie jest widoczny po udostępnieniu: wyświetlenie łącznika udostępnionego dla innych użytkowników może potrwać kilka minut. Jeśli łącznik został dodany do rozwiązania, użytkownicy muszą mieć dostęp do tego rozwiązania, aby zobaczyć łącznik.

Następne kroki

Teraz, po utworzeniu łącznika niestandardowego i zdefiniowaniu jego zachowań, użyj łącznika z:

• Power Automate - narzędzie do automatyzacji procesów
• Power Apps
• Logic Apps
• Copilot Studio

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
• Certyfikowanie swojego łącznika

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.