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

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 definovat rozhraní API, ke kterému se chcete připojit, aby konektor porozuměl operacím a datovým strukturám rozhraní API. V tomto článku vytvoříte vlastní konektor od začátku bez použití formátu Definice OpenAPI k popisu operace mínění v rozhraní API analýzy textu ve službách Azure Cognitive Services (náš příklad pro tuto řadu). Místo toho definujete konektor zcela v průvodci vlastním konektorem.

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

Poznámka:

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 Řešení.

  3. Upravte nebo vytvořte nespravované řešení pro vlastní konektor. Zjistěte, jak vytvořit řešení.

  4. Vyberte rozevírací nabídku Nový vlastní konektor a vyberte Vytvořit z prázdného.

  5. Zadejte název konektoru, například SentimentDemo. Vyberte Pokračovat pro otevření průvodce konektorem, kde v Power Automate dokončíte těchto pět částí:

    • General

    • Zabezpečení

    • Definition

    • Kód (volitelné)

    • Test

      Snímek obrazovky průvodce konektorem v aplikaci Power Automate.

Krok 1: Aktualizujte obecné podrobnosti

V části Obecné zadáváte informace o konektoru, jako je ikona, popis, schéma, hostitel a základní URL. Postupujte následovně:

  1. Pokud chcete nahrát ikonu konektoru ve formátu PNG nebo JPG, vyberte ikonu Nahrát konektor nebo Nahrát v okně ikony. Ujistěte se, že je menší než 1 MB. Můžete také určit barvu pozadí ikony.

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

  3. Vyberte schéma URL vašeho konektoru, HTTPS nebo HTTP.

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

  5. Aktualizujte základní adresu URL, výchozí bod pro všechna volání rozhraní API do konkrétní služby.

  6. Výběrem možnosti Zabezpečení v dolní části přejděte k další části.

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. V části Zabezpečení v části Typ ověřování vyberte v rozevíracím seznamu klíč rozhraní API .

  2. V části Klíč rozhraní API zadejte popisek parametru, název a umístění. Zadejte smysluplný popisek, protože se zobrazí, když někdo poprvé vytvoří spojení s vlastním konektorem. Název parametru a umístění se musí shodovat s tím, co API očekává.

    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.

  4. Výběrem Definice v dolní části přejděte k další části.

Krok 3: Vytvořte definici konektoru

Průvodce vlastním konektorem nabízí řadu možností, jak popsat, jak váš konektor funguje, a jak je zpřístupněn v aplikacích logiky, tocích, aplikacích a agentech. Můžete definovat akce, triggery, odkazy a zásady. 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. Na kartě Definice se v levém podokně zobrazují všechny akce, triggery (pro Logic Apps, Power Automate a Copilot Studio), odkazy a zásady definované pro konektor.

Poznámka:

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

  1. Vyberte položku Nová akce.

  2. V oblasti Obecné přidejte souhrn, popis a ID operace pro tuto akci.

    Parametr Hodnota
    Shrnutí Vrací číselné skóre představující detekované zabarvení
    Description 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. V oblasti Požadavek vyberte Importovat ze vzorku.

  4. Zadejte informace potřebné k připojení k rozhraní API a zadejte text požadavku (uvedený za tabulkou) 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 ukázkový JSON.

    Příklad:

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

  5. V oblasti Odpověď vyberte Přidat výchozí odpověď.

  6. Určete tělo odpovědi a poté vyberte Import. Stejně jako jsme to udělal u textu žádosti, vám tyto informace poskytujeme, obvykle se však jedná o dokumentaci k rozhraní API.

    Příklad:

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

    V oblasti Ověření se zobrazí případné problémy zjištěné v definici rozhraní API.

  7. Opravte případné problémy. Po úspěšném ověření definice by se mělo zobrazit zelené zaškrtnutí.

  8. Vyberte Aktualizovat konektor v pravém horním rohu průvodce.

Aktualizace definice

Změníme několik věcí, aby konektor bylo možné snadněji použít v Logic Apps, Power Automate, Power Apps nebo Copilot Studio.

  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
    Výchozí hodnota 0
    Je povinné Ano

  4. V oblasti Parametr zvolte jazyk>Upravit a pak Upravit a postupujte stejně jako výše u id, s použitím následujících hodnot language:

    Parametr Hodnota
    Titulek Jazyk
    Description Kód jazyka textu o délce dva nebo čtyři znaky
    Výchozí hodnota en
    Je povinné Ano

  5. V oblasti Parametr zvolte text>Upravit a pak Upravit a postupujte stejně jako výše u id a language k přidání následujících hodnot text:

    Parametr Hodnota
    Titulek Text
    Description 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 vrátili zpět na hlavní kartu Definice.

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

  8. Výběrem kódu v dolní části přejděte k další části.

Krok 4: (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. Když je kód použit, má 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 5: Testování konektoru.

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, jsou k dispozici pouze soubory s příponou .cs nebo .csx.

    Snímek obrazovky s nahráním vlastního kódu v části 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, je váš od odstraně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 5: Proveďte test konektoru

Když teď máte vytvořený konektor, otestujte jej 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 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.

    Konektor volá rozhraní API.

  5. Zkontrolujte odpověď, která zahrnuje skóre mínění.

    Screenshot odpovědi konektoru.

Osvědčené postupy pro uživatele rozhraní příkazového řádku

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

  • Last updated on