Vytvoření vlastního konektoru z definice OpenAPI

Poznámka:

Tento článek je součástí série kurzů o vytváření a používání vlastních konektorů v Azure Logic Apps, Microsoft Power Automate a Microsoft Power Apps a volání konektorů jako nástrojů v nástroji Microsoft Copilot Studio. 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 (OAD), která popisuje ukázkové rozhraní API. Při vytváření vlastního konektoru musí být definice OpenAPI menší než 1 MB. Definice OpenAPI musí být ve formátu OpenAPI 2.0 (dříve označovaný 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.

Poznámka:

• Definice OpenAPI musí být ve formátu OpenAPI 2.0 (dříve označovaný jako Swagger). Definice OpenAPI, které jsou ve formát OpenAPI 3.0, nejsou podporovány.

• Použití dokumentu, definice a popisu se vyvíjí ve specifikacích OpenAPI.. Termíny, definice a popis se můžou zobrazit zaměnitelně v tomto článku.

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.

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 k 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í.

   

Použití vlastního konektoru

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

• Použití vlastního konektoru v Power Automate
• Použití vlastního konektoru v Power Apps
• Použití vlastního konektoru v Logic Apps
• Použití vlastního konektoru a akce konektoru v Copilot Studio

Vytvoření vlastního konektoru a akce konektoru pro Microsoft 365 Copilot pro Sales

Můžete vytvořit vlastní konektor z definice OpenAPI v Power Apps nebo Power Automate, který se pak dá použít pro Microsoft 365 Copilot pro Sales. Informace o tom, jak začít, najdete v části Vytvoření vlastního konektoru a akce konektoru.

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.