Vytvoření vlastního konektoru z definice OpenAPI

Poznámka

Toto téma je součástí série kurzů věnované vytváření a používání vlastních konektorů v Azure Logic Apps, Microsoft Power Automate, a Microsoft Power Apps. Přečtěte si přehled vlastních konektorů, abyste porozuměli procesu.

Pokud chcete vytvořit vlastní konektor, musíte popsat rozhraní API, ke kterému se chcete připojit, aby konektor rozuměl operacím a datovým strukturám tohoto rozhraní API. V tomto téma můžete vytvořit vlastní konektor pomocí definice OpenAPI, která popisuje rozhraní API Cognitive Services Text Analytics Sentiment (náš příklad pro tuto řadu).

Další způsob, jak popsat rozhraní API, najdete v části Vytvoření vlastního konektoru od začátku.

Předpoklady

• Definice OpenAPI, která popisuje příklad API. Při vytváření vlastního konektoru musí být definice OpenAPI menší než 1 MB. Definice OpenAPI musí být v OpenAPI 2.0 (dříve známý jako Swagger).

  Pokud existuje více definic zabezpečení, vlastní konektor vybere nejvyšší definici zabezpečení. Vytvoření vlastního konektoru nepodporuje přihlašovací údaje klienta (například aplikaci a heslo) v definici zabezpečení OAuth.

• Klíč rozhraní API pro Cognitive Services Text Analytics API.

• Jedno z následujících předplatných:

  • Azure, pokud používáte Logic Apps
  • Power Automate
  • Power Apps

• Pokud používáte Logic Apps, nejprve vytvořte vlastní konektor Azure Logic Apps.

Import definice OpenAPI

Nyní jste připraveni pracovat s definicí OpenAPI, kterou jste si stáhli. Všechny požadované informace jsou obsaženy v definici a tyto informace si můžete prohlédnout a aktualizovat při procházení průvodce vlastním konektorem.

Začněte importem definice OpenAPI pro Logic Apps nebo Power Automate a Power Apps.

Poznámka

Definice OpenAPI musí být v OpenAPI 2.0 (dříve známý jako Swagger). Definice OpenAPI, které jsou ve formát OpenAPI 3.0, nejsou podporovány.

Import definic OpenAPI pro Logic Apps

1. Přejděte na web Azure Portal a otevřete konektor Logic Apps, který jste vytvořili dříve v tématu Vytvoření vlastního konektoru Azure Logic Apps.

2. V nabídce konektoru zvolte Konektor Logic Apps, a pak zvolte Upravit.

   

3. V části Obecné zvolte Nahrát soubor OpenAPI a pak jděte k definici OpenAPI, kterou jste vytvořili.

   

Poznámka

Tento tutoriál se zaměřuje na REST API, ale můžete také používat rozhraní SOAP API s logickými aplikacemi.

Import definice OpenAPI pro Power Automate a Power Apps

1. Přihlaste se do Power Apps nebo Power Automate.

2. V levém podokně vyberte Data > Vlastní konektory.

   

3. Vyberte Nový vlastní konektor a potom vyberte Importovat soubor OpenAPI.

   

4. Zadejte název vlastního konektoru, přejděte k definici OpenAPI, kterou jste stáhli nebo vytvořili, a vyberte Pokračovat.

   

   Parametr	Hodnota
   Název vlastního konektoru	SentimentDemo

Kontrola obecných podrobností

Od této chvíle budeme ukazovat uživatelské rozhraní Power Automate, ale postup je z velké části stejný pro všechny tři technologie. Poukážeme na jakékoli rozdíly. V této části téma si většinou projdeme uživatelské rozhraní a ukážeme vám, jak hodnoty odpovídají částem souboru OpenAPI.

1. V horní části průvodce se ujistěte, že je název nastavený na SentimentDemo, a pak vyberte Vytvořit konektor.

2. Na stránce Obecné zkontrolujte informace naimportované z definice OpenAPI, včetně hostitele API a základní adresy URL pro rozhraní API. Konektor pomocí hostitele rozhraní API a základní adresy URL určí, jakým způsobem má rozhraní API volat.

   

   Poznámka

   Další informace o připojení k místním rozhraním API, získáte v tématu Připojení k místním rozhraním API pomocí datové brány

   Následující část definice OpenAPI obsahuje informace pro tuto stránku uživatelského rozhraní:

     "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"
     ]
   

Kontrola typu ověřování

Ve vlastních konektorech je k dispozici několik možností ověřování. Rozhraní API Cognitive Services používají autentizaci pomocí klíče API, takže je to specifikováno v definici OpenAPI.

Na stránce Zabezpečení zkontrolujte informace o ověřování pro klíč API.

Popisek se zobrazí, když se někdo poprvé spojí s uživatelským konektorem; můžete vybrat Upravit a změnit tuto hodnotu. Název a umístění parametru musí odpovídat hodnotám, které rozhraní API očekává v tomto případě Ocp-Apim-Subscription-Key a Header.

Následující část definice OpenAPI obsahuje informace pro tuto stránku uživatelského rozhraní:

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

Kontrola definice konektoru

Stránka Definice průvodce vlastním konektorem vám poskytuje mnoho možností pro definování toho, jak váš konektor funguje a jak je veřejně vystaven v logických aplikacích, tocích a aplikacích. Vysvětlíme vám uživatelské rozhraní a v této části si ukážeme několik možností, ale také vás vyzýváme, abyste to prozkoumali sami. Informace o definování konektorů od začátku v tomto uživatelském rozhraní získáte v části Vytvoření definice konektoru.

1. V následující oblasti se zobrazí všechny akce, triggery (pro Logic Apps a Power Automate) a odkazy definované pro daný konektor. V tomto případě se zobrazí definice akce DetectSentiment z OpenAPI. Tento konektor neobsahuje žádné triggery, ale informace o triggerech pro vlastní konektory najdete v tématu Použití webhooků v Azure Logic Apps a Power Automate.

   

2. V oblasti Obecné se zobrazí informace o aktuálně vybrané akci nebo triggeru. Tyto informace tady můžete upravit, včetně vlastnosti Viditelnost pro operace a parametry v aplikaci logiky nebo toku:

   • žádné: obvykle se zobrazí v aplikaci logiky nebo toku

   • rozšířené: skryté v další nabídce

   • interní: skryté pro uživatele

   • důležité: vždy se zobrazí nejprve uživateli

     

3. V oblasti Žádost se zobrazují informace založené na požadavku HTTP, který je součástí definice souboru OpenAPI. V tomto případě vidíte, že je sloveso HTTP POSTa adresa URL je /text/analytics/v2.0/sentiment (celá adresa URL rozhraní API je <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Na parametr tělo se brzy podíváme.

   

   Následující část definice OpenAPI obsahuje informace pro oblasti Obecné a Požadavek uživatelského rozhraní:

   "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. V oblasti Odpověď se zobrazují informace založené na odpovědi HTTP, která je součástí definice souboru OpenAPI. V tomto případě je definovaná pouze odpověď s kódem 200 (úspěšná odpověď), ale můžete definovat i další odpovědi.

   

   Následující část definice OpenAPI obsahuje některé informace související s odpovědí:

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

   Tato část ukazuje dvě hodnoty, které jsou vráceny konektorem: id a score. Zahrnuje jejich datové typy a pole x-ms-summary, což je rozšíření OpenAPI. Další informace o tomto a dalších rozšířeních viz Prodloužení definice OpenAPI pro vlastní konektor.

5. V oblasti Ověření se zobrazí případné problémy zjištěné v definici rozhraní API. Nezapomeňte tuto část zkontrolovat před uložením konektoru.

   

Aktualizace definice

Definice OpenAPI, kterou jste stáhli, představuje dobrý základní příklad, ale můžete pracovat i s definicemi, které vyžadují hodně aktualizací, aby konektor bylo možné snadněji použít v aplikaci logiky, toku nebo aplikaci. Ukážeme vám, jak provést změnu definice.

1. V oblasti Požadavek vyberte text a pak Upravit.

   

2. V oblasti Parametr se teď zobrazí tři parametry, které rozhraní API očekává: ID, Language, a Text. Vyberte ID a pak Upravit.

   

3. V oblasti Vlastnost schématu aktualizujte popis pro parametr a pak vyberte Zpět.

   

   Parametr	Hodnota
   Popis	Číselný identifikátor každého odeslaného dokumentu

4. V oblasti Parametr vyberte Zpět a budete přesměrováni na hlavní stránku definice.

5. V pravém horním rohu průvodce vyberte Aktualizovat konektor.

Stáhněte si aktualizovaný soubor OpenAPI

Vlastní konektor můžete vytvořit ze souboru OpenAPI nebo od začátku (v Power Automate a Power Apps). Bez ohledu na způsob vytvoření konektoru můžete stáhnout definici OpenAPI, kterou služba interně využívá.

• V Logic Apps ji stáhnete z vlastního konektoru.

  

• V Power Automate nebo Power Apps stáhněte ze seznamu vlastních konektorů.

  

Zkouška konektoru

Když teď máte vytvořený konektor, otestujte ho a ujistěte se, že funguje správně. Testování je v současné době k dispozici pouze v Power Automate a Power Apps.

Důležité

Při použití klíče API doporučujeme testovat konektor ihned po jeho vytvoření. Může trvat několik minut, než bude konektor připraven k připojení k rozhraní API.

1. Na stránce Test vyberte Nové připojení.

   

2. Zadejte klíč rozhraní API z rozhraní API pro analýzu textu a pak vyberte Vytvořit připojení.

   

3. Vraťte se na zkušební stránku a proveďte jeden z následujících úkonů:

   • V Power Automate budete přesměrování zpět na stránku Test. Vyberte ikonu aktualizace a ujistěte se, že se aktualizovaly informace o připojení.

     

   • V Power Apps budete přesměrováni na seznam dostupných připojení v aktuálním prostředí. V pravém horním rohu vyberte ikonu ozubeného kola a potom Vlastní konektory. Zvolte konektor, který jste vytvořili, a přejděte zpět na stránku Test.

     

4. Na stránce Test zadejte hodnotu pro pole text (v ostatních polích se použijí výchozí hodnoty, které jste nastavili dříve) a pak vyberte Otestovat funkci.

   

5. Konektor volá API a vy můžete zkontrolovat odpověď, která zahrnuje skóre mínění.

   

Další kroky

Teď, když jste vytvořili vlastní konektor a nadefinovali jeho chování, můžete konektor použít.

• Použití vlastního konektoru z toku
• Použití vlastního konektoru z aplikace
• Použití vlastního konektoru z aplikace logiky

Konektor můžete také sdílet v rámci vaší organizace nebo pro něj získat certifikaci, aby ho mohli využívat i lidé mimo vaši organizaci.

• Sdílejte svůj konektor
• Certifikujte svůj konektor

Poskytnutí názorů

Velmi si vážíme vašich názorů na problémy s naší platformou konektorů nebo nových nápadů na funkce. Chcete-li poskytnout zpětnou vazbu, přejděte do části Odeslat problémy nebo získat pomoc s konektory a vyberte typ zpětné vazby.