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

  • Článek

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.

Poznámka

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

Další způsoby popisu rozhraní API naleznete v následujících tématech:

Poznámka

Aktuálně můžete vytvořit vlastní konektor od začátku v Power Automate a Power Apps. V Logic Apps musíte začít alespoň se základní definicí OpenAPI nebo kolekcí Postman.

Předpoklady

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.

    Snímek obrazovky polí na stránce 'manifestu modulu plug-in'.

    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.

    Snímek obrazovky polí na stránce 'Podrobnosti akcí modulu plug-in'.

    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.

    Snímek obrazovky polí na stránce 'Parametry'.

    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.

Poznámka

  • Tento krok je nepovinný. Vytváření konektoru bez použití kódu můžete dokončit, i když budete tento krok ignorovat a přejdete k části Krok 6: Testování konektoru.
  • Podpora pro vlastní kód je k dispozici ve verzi Public Preview.

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.

    Screenshot Nahrajte svůj vlastní kód.

    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.

    Screenshot Vybrat akce a spouštěče.

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.

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

      Snímek obrazovky obnovení připojení.

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

    Screenshot odpovědi konektoru.

(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:

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.

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.