Tworzenie łącznika niestandardowego na podstawie definicji interfejsu OpenAPI

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 – analiza tekstu Sentiment API (nasz przykład dla tej serii).

Aby poznać inny sposób opisywania interfejsu API, przejdź do Tworzenie niestandardowego łącznika od podstaw.

Wymagania wstępne

• Definicja interfejsu OpenAPI (OAD), która opisuje przykładowy interfejs API. Podczas tworzenia niestandardowego łącznika definicja OpenAPI musi mieć mniej niż 1 MB. Definicja interfejsu OpenAPI musi być w formacie OpenAPI 2.0 (wcześniej 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:

  • Azure, jeśli są używane usługi Logic Apps
  • Power Automate - narzędzie do automatyzacji procesów
  • Power Apps

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

Importuj definicję OpenAPI

W tym samouczku użyto przykładowej definicji OpenAPI dla interfejsu API analizy tonacji tekstu w ramach usługi Cognitive Services. Aby wykonać poniższe czynności, utwórz lokalny plik JSON o nazwie SentimentDemo.json i wklej następującą definicję interfejsu OpenAPI 2.0:

{
  "swagger": "2.0",
  "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"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  },
  "security": [{"api_key": []}],
  "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",
        "parameters": [{
          "in": "body",
          "name": "body",
          "schema": {
            "type": "object",
            "properties": {
              "documents": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "string", "x-ms-summary": "id"},
                    "language": {"type": "string", "x-ms-summary": "language"},
                    "text": {"type": "string", "x-ms-summary": "text"}
                  }
                }
              }
            }
          }
        }],
        "responses": {
          "200": {
            "description": "200",
            "schema": {
              "type": "object",
              "properties": {
                "documents": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "score": {"type": "number", "format": "float", "description": "score", "x-ms-summary": "score"},
                      "id": {"type": "string", "description": "id", "x-ms-summary": "id"}
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Teraz możesz zaimportować tę definicję interfejsu OpenAPI. Definicja zawiera wszystkie wymagane informacje. Kreator łącznika niestandardowego umożliwia przejrzenie tych informacji i ich ewentualne zaktualizowanie.

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

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 łącznika wybierz Łącznik Logic Apps, a następnie wybierz Edytuj.

   

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

   

Zaimportuj definicję OpenAPI dla Power Automate i Power Apps

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

2. W okienku po lewej stronie wybierz pozycję Rozwiązania, a następnie otwórz rozwiązanie, którego chcesz użyć, lub utwórz nowe.

3. Wybierz kolejno pozycje Nowy>Automatyzacja>Łącznik niestandardowy.

4. Wybierz pozycję Importuj plik OpenAPI.

5. Wprowadź nazwę łącznika niestandardowego, wybierz utworzony plik SentimentDemo.json, a następnie wybierz Kontynuuj.

   

   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.

   

   Notatka

   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.

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ść. Nazwa i lokalizacja parametru muszą być zgodne z oczekiwaniami interfejsu API, w tym przypadku Ocp-Apim-Subscription-Key i Nagłówek.

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.

   

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

     

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.

   

   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.

   

   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.

   

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.

   

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.

   

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

   

   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ć z pliku OpenAPI lub od podstaw ( w 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.

  

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

  

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.

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

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

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

   • W Power Automate nastąpi powrót do strony 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 prawym górnym rogu ekranu wybierz ikonę koła zębatego, a następnie wybierz Łączniki niestandardowe. Wybierz utworzony łącznik, a następnie wróć do strony Testuj.

     

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

   

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

   

Używanie łącznika niestandardowego

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

• Używanie łącznika niestandardowego w Power Automate
• Używanie łącznika niestandardowego w Power Apps
• Używanie łącznika niestandardowego w aplikacji logiki
• Używanie łącznika niestandardowego i akcji łącznika w Copilot Studio

Tworzenie łącznika niestandardowego i akcji łącznika dla Microsoft 365 Copilot dla działów sprzedaży

Można utworzyć niestandardowy łącznik z definicji OpenAPI w Power Apps lub Power Automate, który może być następnie użyty do Microsoft 365 Copilot dla działów sprzedaży. Przejdź do Utwórz niestandardowy łącznik i akcję łącznika, aby dowiedzieć się, jak zacząć.

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.