Vytvoření vlastního konektoru od základu

Tento článek 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.

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ématu vytvoříte vlastní konektor od začátku bez použití definice OpenAPI k popisu operace zabarvení rozhraní Azure Cognitive Services Text Analytics API (náš příklad pro tuto sérii). Místo toho popisujete konektor zcela ve vlastním průvodci konektorem.

Další způsob, jak popsat rozhraní API, najdete v části Vytvoření vlastního konektoru z definice OpenAPI .

Předpoklady

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

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

  • Power Automate
  • Power Apps

Spuštění průvodce vlastním konektorem

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

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

3. Vyberte Nový vlastní konektor > Vytvořit z prázdného.

4. Zadejte název vlastního konektoru a potom zvolte Pokračovat.

   Parametr	Hodnota
   Název vlastního konektoru	SentimentDemo

Krok 1: Aktualizujte obecné podrobnosti

Od této chvíle budeme ukazovat uživatelské rozhraní Power Automate, ale postup je z velké části stejný pro všechny technologie. Poukážeme na jakékoli rozdíly.

Na kartě Obecné můžete provést tyto akce:

1. V poli Popis zadejte smysluplnou hodnotu. Tento popis se zobrazí v podrobnostech o vlastním konektoru a ostatním uživatelům může pomoct rozhodnout, jak by pro ně konektor mohl být užitečný.

2. Aktualizujte pole Hostitel na adresu rozhraní API Text Analytics. Konektor pomocí hostitele rozhraní API a základní adresy URL určí, jakým způsobem má rozhraní API volat.

   Parametr	Hodnota
   Description	Pomocí rozhraní API služeb Cognitive Services pro analýzu mínění v textu určuje, jestli je text pozitivní nebo negativní
   Hostitelský počítač	westus.api.cognitive.microsoft.com

Krok 2: Zadejte typ ověřování

Ve vlastních konektorech je k dispozici několik možností ověřování. Rozhraní API Cognitive Services používají ověřování pomocí klíče API, takže to je to, co určíte pro tento kurz.

1. Na kartě Zabezpečení pod Typ ověření vyberte Klíč API.

2. V části Klíč rozhraní API zadejte popisek, název a umístění parametru. Zadejte smysluplný popisek, protože tento popisek se zobrazí, když se někdo poprvé připojí pomocí vlastního konektoru. Název parametru a umístění se musí shodovat s tím, co API očekává. Vyberte Připojit.

   Parametr	Hodnota
   Popisek parametru	Klíč rozhraní API
   Název parametru	Ocp-Apim-Subscription-Key
   Umístění parametru	Hlavička

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

Krok 3: Vytvořte definici konektoru

Průvodce vlastním konektorem vám nabízí mnoho možností pro definování, jak váš konektor funguje a jak je zpřístupněn 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.

Vytvoření akce

První věc, kterou musíte udělat, je vytvořit akci, která volá operaci zabarvení rozhraní API.

1. Na kartě Definice se v levém podokně obrazí všechny akce, triggery (pro Logic Apps a Power Automate) a odkazy definované pro daný konektor. Vyberte položku Nová akce.

   V tomto konektoru nejsou žádné triggery. O triggerech pro vlastní konektory najdete informace v části Použití webhooků v Azure Logic Apps a Power Automate.

2. V oblasti Obecné se zobrazí informace o aktuálně vybrané akci nebo triggeru. Přidejte souhrn, popis a ID operace pro tuto akci.

   Parametr	Hodnota
   Shrnutí	Vrací číselné skóre představující detekované zabarvení
   Popis	Rozhraní API vrací číselné skóre v rozsahu 0 až 1. Skóre blížící se 1 značí kladné mínění, zatímco skóre blížící se 0 značí záporné mínění.
   ID operace	DetectSentiment

   Vlastnost Viditelnost nechte nastavenou na žádná. Tato vlastnost pro operace a parametry v logické aplikaci nebo toku má následující možnosti:

   • žádné: obvykle se zobrazí v aplikaci logiky nebo toku
   • pokročilé: skryté pod jinou nabídkou
   • interní: skryté pro uživatele
   • důležité: vždy se zobrazí nejprve uživateli

3. Oblast Žádost zobrazuje informace na základě požadavku HTTP na akci. Vyberte Importovat z ukázky.

4. Zadejte informace potřebné k připojení k rozhraní API a určete text požadavku (zadaný za následujícím obrázkem) a potom vyberte možnost Importovat. Tyto informace poskytujeme za vás, ale pro veřejné API tyto informace obvykle získáte z dokumentace, jako je např. rozhraní API analýzy textu (v2.0).

   Parametr	Hodnota
   Verb (Příkaz)	POST
   URL	<https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
   Body	Použijte následující kód JSON

   Příklad:

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

5. Oblast Žádost zobrazuje informace na základě reakce HTTP na akci. Vyberte Přidat výchozí odpověď.

6. Určete tělo odpovědi a poté vyberte Import. Stejně jako v případě těla požadavku vám tyto informace poskytneme za obrázkem, ale obvykle jsou uvedeny v dokumentaci rozhraní API.

   Příklad:

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

7. V oblasti Ověření se zobrazí případné problémy zjištěné v definici rozhraní API. Zkontrolujte stav a v pravém horním rohu průvodce vyberte Aktualizovat konektor.

Aktualizace definice

Teď změníme několik věcí, aby konektor bylo možné snadněji použít v aplikaci logiky, toku nebo aplikaci.

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 hodnoty pro parametr a pak vyberte Zpět.

   Parametr	Hodnota
   Titulek	ID
   Description	Identifikátor každého odeslaného dokumentu
   Default value	0
   Je povinné	Ano

4. V oblasti Parametr vyberte jazyk > Upravit a poté opakujte postup, který které jste použili pro id v krocích 2 a 3 tohoto postupu, s následujícími hodnotami.

   Parametr	Hodnota
   Titulek	Jazyk
   Description	Kód jazyka textu o délce dva nebo čtyři znaky
   Default value	en
   Je povinné	Ano

5. V oblasti Parametr vyberte text > Upravit a poté opakujte postup, který které jste použili pro id v krocích 2 a 3 tohoto postupu, s následujícími hodnotami.

   Parametr	Hodnota
   Titulek	Text
   Popis	Text, u kterého se má analyzovat mínění
   Výchozí hodnota	Žádné
   Je povinné	Ano

6. V oblasti Parametr vyberte Zpět, abyste se dostali zpět na hlavní kartu Definice.

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

Krok 4: (Volitelné) Povolte svůj konektor jako plugin AI

Kartu AI Plugin (preview) pro konektor použijte pouze v případě, že plánujete certifikovat svůj konektor. Aby bylo možné konektor použít jako plugin AI, musí být konektor certifikovaný.

Než povolíte konektor jako zásuvný modul AI, ujistěte se, že rozumíte případu použití scénářů zásuvného modulu AI a že jste si prostudovali další aspekty, jako je podpora, osvědčené postupy a doporučení. Další informace: Vytvoření modulu plug-in konektoru s AI (preview)

1. V levém navigačním podokně vyberte Vlastní konektory.

   Pokud nevidíte Vlastní konektory, vyberte Další > Objevit vše > Vlastní konektory. Tato možnost se zobrazí v levém navigačním panelu.

2. Vyberte možnost z nabídky Nový vlastní konektor v pravém horním rohu.

3. Ujistěte se, že jste dokončili Krok 1, Krok 2 a Krok 3 v tomto článku.

4. Vyberte kartu Modul plug-in AI (preview).

5. V části Manifest modulu plug-in zadejte podrobnosti, abyste tento konektor povolili jako modul plug-in AI.

   

   Pole	Description
   Manifest modulu plug-in: Název	Název modulu plug-in AI.
   Manifest modulu plug-in: Popis	Popis modulu plug-in AI. Další informace: Vytvoření modulu plug-in konektoru s AI (preview)
   Manifest modulu plug-in: Kontaktní e-mail	E-mailová adresa kontaktu pro tento plugin AI.
   Manifest pluginu: URL s právními informacemi	Veřejně přístupné místo, kde jsou zveřejněny právní informace týkající se vašeho pluginu AI.

6. Přejděte dolů do sekce Podrobnosti akcí modulu plug-in a zadejte podrobnosti o akci pro každou akci ve svém pluginu AI konektoru.

   

   Pole	Description
   Podrobnosti o akci pluginu: Shrnutí	Souhrn o každé akci pluginu AI, kterou mohou uživatelé provádět.
   Podrobnosti o akci pluginu: Popis	Popis každé akce, kterou mohou uživatelé provést v souvislosti s tímto konkrétním krokem akce modulu plug-in AI.
   Zaškrtávací políčko: Povolit jako operaci s modulem plug-in copilota	Když je zaškrtávací políčko zaškrtnuto, je operace zásuvného modulu AI povolena.
   Zaškrtávací políčko: Vyžaduje se potvrzení uživatele?	Pokud je zaškrtávací políčko zaškrtnuto, je vyžadováno potvrzení uživatele.

   Tip

   Pokud potřebujete pomoc s definováním svých akcí, zapněte přepínač Swagger editor.

7. Přejděte dolů do sekce Parametr a zadejte podrobnosti o parametrech pro váš modul plug-in konektoru AI.

   

   Pole	Description
   Parametr: Název	Název parametru. Používejte identifikovatelné názvy, jako je Identifikátor účtu namísto ID.
   Parametr: Popis	Popis parametru. Použijte popisné vysvětlení, například Datum narození pro kontakt ve formátu MM/DD/RRRR namísto b_ datum. Takové názvy a popisy pomáhají LLM (velké jazykové modely) efektivně interagovat s pluginem AI.
   Parametr: Souhrn	Souhrnné informace o parametru.
   Parametr: Výchozí hodnota	Výchozí hodnota parametru.

8. V sekci Požadavek pod sekcemi Modul plug-in AI (preview) vyberte vstupní parametr a poté zadejte popis.

Krok 5: (Volitelné) Použití podpory pro vlastní kód

Vlastní kód transformuje datové části požadavků a odpovědí nad rámec stávajících šablon zásad. Transformace zahrnují odesílání externích požadavků na načtení dalších dat. Při použití kódu bude mít přednost před definicí bez kódu. To znamená, že se kód spustí a my neodešleme požadavek na back-end.

Můžete buď vložit váš kód, nebo nahrát soubor s vaším kódem. Kód musí:

• Být napsán v jazyce C#.
• Mít maximální dobu provádění pět sekund.
• Velikost souboru není větší než 1 MB.

Pokyny a ukázky psaní kódu najdete v části Zápis kódu do vlastních konektorů.

Nejčastější dotazy týkající se vlastního kódu najdete v části Časté dotazy k vlastnímu kódu.

1. Na kartě Kód vložte svůj vlastní kód pomocí jedné z následujících možností:

   • kopírovat/vložit
   • vyberte tlačítko Nahrát.

   Pokud se rozhodnete nahrát svůj vlastní kód, budou k dispozici pouze soubory s příponou .cs nebo .csx.

   

   Důležité

   V současné době podporujeme pouze zvýrazňování syntaxí v editoru kódu. Nezapomeňte svůj kód otestovat lokálně.

2. Jakmile kód vložíte nebo nahrajete, vyberte přepínač vedle možnosti Kód zakázán a povolte svůj kód. Název přepínače se změní na Kód povolen.

   Svůj kód můžete kdykoli povolit nebo zakázat. Pokud je přepínač nastaven na Kód zakázán, bude váš kód smazán.

3. Výběrem možnosti v rozevírací nabídce zvolte akce a triggery, které chcete použít na svůj vlastní kód. Pokud není vybrána žádná operace, akce a spouštěče se použijí na všechny operace.

   

Krok 6: Proveďte test 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.

1. Na kartě Test vyberte Nové připojení.

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

   Poznámka

   U rozhraní API, která vyžadují ověřování na doručitele, přidejte před klíčem API doručitele a jednu mezeru.

3. Vraťte se na kartu Test a proveďte jeden z následujících úkonů:

   • (V Power Automate) Vrátíte se zpět na kartu Test. Vyberte ikonu aktualizace, abyste se ujistili, že jsou informace o připojení aktualizovány.

     

   • (V Power Apps) Budete přesměrováni na seznam dostupných připojení v aktuálním prostředí. V levém podokně vyberte Data > Vlastní konektory. Vyberte konektor, který jste vytvořili, a poté se vraťte na kartu Test.

4. Na kartě Test zadejte hodnotu pro pole text (ostatní pole používají výchozí hodnoty, které jste nastavili dříve), a pak vyberte Zkušební provoz.

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

   

(Pro uživatele CLI) Osvědčené postupy

• Stáhněte si všechny vaše konektory a k uložení souborů použijte git nebo jakýkoli jiný systém správy zdrojového kódu.

• V případě nesprávné aktualizace nasaďte konektor znovu opětovným spuštěním příkazu update se správnou sadou souborů ze systému správy zdrojového kódu.

• Před nasazením vlastního konektoru a souboru nastavení do produkčního prostředí je otestujte v testovacím prostředí.

• Vždy pečlivě zkontrolujte správnost ID prostředí a konektoru.

Další kroky

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

• Toku
• Aplikace
• Logické aplikace

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.