Vytvoření vlastního konektoru z definice OpenAPI

  • Článek

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:

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

    Úprava konektoru Logic Apps.

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

    Nahrajte soubor OpenAPI.

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.

    Vyberte vlastní konektor.

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

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

    Nahrajte kolekci.

    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.

    Obecná stránka Vlastní konektor.

    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.

Parametry klíče rozhraní 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.

    Stránka definice - akce a triggery.

  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

      Stránka Definice - obecné.

  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.

    Stránka Definice - požadavek.

    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.

    Stránka Definice - odpověď.

    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.

    Stránka Definice - ověření.

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.

    Upravte tělo žádosti.

  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.

    Úprava ID těla žádosti.

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

    Upravte vlastnost schématu.

    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.

    Stažení definice OpenAPI pro Logic Apps.

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

    Stažení definice OpenAPI pro Power Automate.

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

    Nové připojení.

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

    Vytvoření 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í.

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

      Ikona zařízení v provozu.

  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.

    Operace Test.

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

    Odpověď konektoru.

Další kroky

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

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.