Sdílet prostřednictvím

Příprava souborů konektorů a pluginů Power Platform pro certifikaci

  • Článek

Tento proces je pro ověřené i nezávislé vydavatele.

Až dokončíte vývoj vlastního konektoru nebo pluginu, podle těchto kroků ho připravte k certifikaci a vygenerujte soubory konektoru nebo pluginu, které odešlete do společnosti Microsoft.

Poznámka

Tento článek poskytuje informace o certifikaci vlastních konektorů v Azure Logic Apps, Power Automate a Power Apps a pluginů v Copilotu. Před provedením kroků v tomto článku si přečtěte část Certifikace konektoru nebo pluginu.

Krok 1: Zaregistrujte svůj konektor nebo plugin (platí pouze pro nezávislé vydavatele)

Tato část se nevztahuje na ověřené vydavatele.

K žádosti o certifikaci není nutné, abyste už měli dokončený vývoj vlastního konektoru nebo pluginu. Chcete-li zahájit proces certifikace, zaregistrujte svůj konektor nebo plugin pro certifikaci vyplněním našeho registračního formuláře.

Do dvou pracovních dnů očekávejte e-mail od kontaktního pracovníka společnosti Microsoft, který:

  • Rozumí vašemu vlastnímu konektoru, konektoru nebo pluginu.
  • Zjistí více o pokroku při vývoji.
  • E-maily o procesu certifikace.

Krok 2: Splňte požadavky na odeslání pro konektory

Pro udržení vysokého standardu kvality a konzistence mezi našimi certifikovanými konektory má Microsoft sadu požadavků a pokynů, které musí váš vlastní konektor dodržovat pro certifikaci.

Pojmenujte svůj konektor

Název musí splňovat následující požadavky.

  • Musí existovat a musí být v angličtině.
  • Musí být jedinečný a rozlišitelný od jakéhokoli stávajícího názvu konektoru nebo pluginu.
  • Měl by být název vašeho produktu nebo organizace.
  • Měl by vycházet z existujících vzorů pojmenování certifikovaného konektoru nebo pluginu. Pro nezávislé vydavatele by název konektoru by měl vypadat dle vzoru Connector and/or plugin Name (Independent Publisher).
  • Název nesmí být delší než 30 znaků.
  • Nesmí obsahovat slova rozhraní API, konektor ani žádný z názvů produktů Power Platform (například Power Apps).
  • Nemůže končit nealfanumerickým znakem, včetně návratu na začátek řádku, nového řádku nebo mezery.

Příklady

  • Dobré názvy konektorů nebo pluginů: Azure Sentinel*, *Office 365 Outlook
  • Špatné názvy konektorů nebo pluginů: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Napište popis svého konektoru

Popis musí splňovat následující požadavky.

  • Musí existovat a musí být v angličtině.
  • Musí být bez gramatických a pravopisných chyb.
  • Měl by stručně popsat hlavní účel a hodnotu nabízenou vaším konektorem.
  • Nesmí být kratší než 30 znaků nebo delší než 500 znaků.
  • Nesmí obsahovat žádné názvy produktů Power Platform (například „Power Apps“).

Navrhněte ikonu pro svůj konektor (platí pouze pro ověřené majitele stránek)

Tato část se nevztahuje na nezávislé vydavatele.

  • Vytvořte logo s poměrem stran 1:1 v rozsahu 100 x 100 až 230 x 230 pixelů (bez zaoblených hran).
  • Použijte neprůhledné, nebílé pozadí (#ffffff) a jinou než výchozí barvu (#007ee5), které odpovídá zadané barvě pozadí ikony.
  • Ikona musí být jiná než jakákoli jiná ikona certifikovaného konektoru.
  • Odešlete logo ve formátu PNG jako <icon>.png.
  • Nastavte rozměry loga pod 70 % pro výšku obrázku a šířku s konzistentním pozadím.
  • Ujistěte se, že barva značky je platná hexadecimální barva a neměla by být bílá (#ffffff) ani výchozí (#007ee5).

Definování souhrnů a popisů operací a parametrů

Shrnutí a popisy musí splňovat následující požadavky.

  • Musí existovat a musí být v angličtině.
  • Musí být bez gramatických a pravopisných chyb.
  • Souhrny operací a parametrů by měly být fráze, 80 znaků nebo kratší, a měly by obsahovat pouze alfanumerické znaky nebo závorky.
  • Popisy operací a parametrů by měly být plné, popisné věty a měly by končit interpunkcí.
  • Nesmí obsahovat žádné názvy produktů Microsoft Power Platform (například „Power Apps").

Definování přesných provozních reakcí

Odpovědi operací musí splňovat následující požadavky.

  • Odpovědi operace definujte pomocí přesného schématu pouze u očekávaných odpovědí.
  • Nepoužívejte výchozí odpovědi s přesnou definicí schématu.
  • Zadejte platné definice schématu odpovědi pro všechny operace ve swaggeru.
  • Prázdná schémata odpovědí nejsou povolena s výjimkou zvláštních případů, kdy je schéma odpovědi dynamické. To znamená, že ve výstupu se nezobrazí žádný dynamický obsah a tvůrci musí k analýze odpovědi použít JSON.
  • Prázdné operace nejsou povoleny.
  • Odstraňte prázdné vlastnosti, pokud nejsou vyžadovány.

Ověřte vlastnosti Swaggeru

Vlastnosti musí splňovat následující požadavky.

  • Ujistěte se, že "openapidefinition" je ve správně naformátovaném souboru JSON.
  • Zajistěte, aby definice swaggeru odpovídala standardu OpenAPI 2.0 a rozšířenému standardu konektorů.

Ověřte parametry připojení

Parametry musí splňovat následující požadavky.

  • Ujistěte se, že vlastnost je aktualizována vhodnými hodnotami pro "UIDefinition" (zobrazované jméno, popis).

  • Pokud váš parametr připojení používá Základní ověřování, ujistěte se, že je JSON správně naformátován podle následujícího příkladu.

    {
  "username": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourUsernameLabel",
      "description": "The description of YourUsernameLabel for this api",
      "tooltip": "Provide the YourUsernameLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": true,
        "required": "true"
        }
  }
},
  "password": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourPasswordLabel",
      "description": "The description of YourPasswordLabel for this api",
      "tooltip": "Provide the YourPasswordLabel tooltip text",
      "constraints": {
        "tabIndex": 3,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Pokud váš parametr připojení má APIKey jako ověřování, ujistěte se, že je JSON správně naformátován podle následujícího příkladu.

    {
  "api_key": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourApiKeyParameterLabel",
      "tooltip": "Provide your YourApiKeyParameterLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Pokud váš parametr připojení má generický OAuth jako ověřování, ujistěte se, že je JSON správně naformátován podle následujícího příkladu.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "oauth2",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "AuthorizationUrl": {
          "value": "https://contoso.com"
        },
        "TokenUrl": {
          "value": "https://contoso.com"
        },
        "RefreshUrl": {
          "value": "https://contoso.com"
        }
      },
      "clientId": "YourClientID"
    },
    "uiDefinition": null
  }
}

  • Pokud má váš parametr připojení poskytovatele identity OAuth2, ujistěte se, že poskytovatel identity je ze seznamu podporovaných poskytovatelů OAuth2. Následuje příklad poskytovatele identity GitHub OAuth2:

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "github",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {},
      "clientId": "YourClientId"
    },
    "uiDefinition": null
  }
}

  • Pokud váš parametr připojení má Microsoft Entra ID jako ověřování, ujistěte se, že je JSON správně naformátován podle následujícího příkladu.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "aad",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "LoginUri": {
          "value": "https://login.microsoftonline.com"
        },
        "TenantId": {
          "value": "common"
        },
        "ResourceUri": {
          "value": "resourceUri"
        },
        "EnableOnbehalfOfLogin": {
          "value": false
        }
      },
      "clientId": "AzureActiveDirectoryClientId"
    },
    "uiDefinition": null
  }
}

Vytváření kvalitních anglických jazykových řetězců

Konektory jsou lokalizovány jako součást lokalizace Power Automate; proto, když vyvíjíte konektor, kvalita anglických řetězců je klíčem ke kvalitě překladu. Zde je několik hlavních oblastí, na které je třeba se zaměřit při vytváření hodnot řetězců, které poskytnete.

  • Nezapomeňte spustit program kontroly pravopisu, abyste zajistili, že všechny hodnoty řetězce neobsahují typografické chyby. Pokud existuje nějaký neúplný anglický jazykový řetězec, výsledek překladu je neúplný nebo nesprávný v kontextu.

  • Ujistěte se, že věta je v úplném tvaru. Pokud věta není úplná, může to také vést k nižší kvalitě překladů.

  • Ujistěte se, že význam věty je jasný. Pokud je význam věty nejednoznačný, může to také způsobit nižší kvalitu nebo nesprávné překlady.

  • Ujistěte se, že souhrny, x-ms-souhrny a popisy jsou gramaticky správné. Nekopírujte je. Chcete-li zjistit, jak se zobrazují v produktu, přejděte na Pokyny pro řetězec konektorů.

  • Pokud je to možné, vyhněte se složeným řetězcům modulu runtime. Místo toho použijte plně vytvořené věty. Zřetězené řetězce nebo věty znesnadňují překlad nebo mohou způsobit nesprávný překlad.

  • Pokud používáte zkratky, ujistěte se, že jsou zapsány velkými písmeny, aby byly jasně srozumitelné. Sníží se tak možnost záměny za typografickou chybu.

  • Řetězce ve formě CaMel (například minimizeHighways nebo MinimizeHighways) jsou obvykle považovány za nepřeložitelné. Pokud chcete lokalizovat hodnotu řetězce, musíte opravit formu CaMel.

Krok 3: Spusťte Kontrolu řešení k ověření vašeho konektoru.

Kontrola řešení je mechanismus pro provádění statické analýzy, aby se zajistilo, že váš konektor splňuje standardy požadované společností Microsoft pro certifikaci. Přidejte svůj konektor do řešení v Power Automate nebo Power Apps a spusťte kontrolu řešení podle pokynů na stránce Ověření vlastního konektoru pomocí kontroly řešení.

V tomto videu se dozvíte, jak spustit kontrolu řešení:

Krok 4: Přidání metadat

Artefakty konektoru (soubory) musí obsahovat specifická metadata popisující konektor a jeho koncovou službu. Informace poskytované v metadatech jsou zveřejněny v naší dokumentaci ke konektoru a jsou veřejně přístupné všem uživatelům. Neposkytujte žádné soukromé ani důvěrné informace a pokud se vyskytnou nějaké problémy s poskytnutím těchto informací, informujte nás o tom prostřednictvím svého kontaktu se společností Microsoft. Chcete-li se dovědět, jak jsou metadata zdokumentována, navštivte některou ze stránek dokumentace specifických pro konektory v části Reference konektoru.

Krok 4a: Vlastnosti vydavatele a stackOwner

  • "vydavatel" je název vaší společnosti nebo organizace. Zadejte úplný název společnosti (například „Contoso Corporation“). Musí být v alfanumerickém formátu.
  • "stackOwner" je vlastnická společnost nebo organizace back-endového zásobníku služeb, ke kterému se konektor připojuje. Musí být v alfanumerickém formátu.
Vydavatel Description Příklad
Ověřeno Vydavatel a stackOwner jsou stejní, pokud ISV nevytváří konektor jménem stackOwner. "vydavatel": "Tesla",
"stackOwner": "Tesla"
Nezávislý Musíte uvést vlastníka zásobníku a vlastníka vydavatele. "vydavatel": "Nirmal Kumar",
"stackOwner": "ITGlue"

Umístění souboru: openapidefinition.json

Syntaxe: Vlastnosti publisher a stackOwner existují jako vlastnosti nejvyšší úrovně v rámci soubor openapidefinition.json. Přidejte následující zvýrazněné řádky, jak je znázorněno. Ujistěte se, že zadáváte název vlastnosti a schéma přesně tak, jak je znázorněno.

Snímek obrazovky zobrazující vlastnosti vydavatel a stackOwner, které jsou k dispozici ve vzorových fragmentech kódu.

Krok 4c: Ukázka fragmentů kódu

Následující fragmenty kódu můžete použít ke zkopírování a zadání svých informací. Zajistěte, abyste fragmenty přidali do správných souborů na správných místech, jak je popsáno v předchozí části.

    "publisher": "_____",
    "stackOwner": "_____"

    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }

    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

Poznámka

V používání vlastnosti stackOwner a našeho nástroje CLI Paconn existuje aktuální omezení. Další informace získáte v části Omezení v souboru README.

Krok 4d: Formátování souboru JSON a omezení

  • Ujistěte se, že jsou vaše vlastnosti správně zarovnány.

  • Vložte svůj JSON do Visual Studio Code. Neváhejte použít rozšíření, jako je kontrola pravopisu, a pluginy, jako jsou pluginy JSON.

  • Soubory Swagger by neměly být větší než 1 MB.

    • Zvažte design vašeho konektoru, než jej začnete stavět. Vyhodnoťte, zda by měl být konektor rozdělen na dva (2) nebo více konektorů.
    • Větší swagger soubory mohou způsobit zpoždění při použití konektoru.

    Na platformě jsou například tři (3) různé konektory HubSpot.

    Snímek obrazovky se složkami pro tři konektory HubSpot.

Krok 5: Splnění požadavků na odeslání pro pluginy

Tato část platí, pokud k certifikaci odesíláte také související plugin konektoru.

Krok 6: Připravte artefakty konektoru nebo pluginu

Poznámka

  • Před certifikací se ujistěte, že jste dodrželi specifikace a zajistili kvalitu konektoru nebo pluginu. V opačném případě se certifikace zpozdí, protože vás budeme muset požádat o provedení změn.
  • Poskytněte produkční verzi adresy URL hostitele. Zkušební, vývojářské a testovací adresy URL hostitele nejsou povoleny.

Odesíláte společnosti Microsoft sadu souborů, což je generování řešení z portálu maker nebo Microsoft Copilot Studio. Chcete-li zabalit soubory, postupujte podle kroků v této části.

Průvodce balením konektorů a pluginů

Postupy v této části vás provedou různými scénáři balení. Pokud chcete zabalit pouze vlastní konektor, použijte první scénář. Pokud chcete zabalit jak vlastní konektor , tak pluginy, použijte druhý scénář. Pokud chcete zabalit existující konektor a pluginy, použijte poslední scénář.

Zabalení vlastního konektoru a odeslání k certifikaci

  1. Vytvoření vlastního konektoru do řešení.

  2. Spusťte kontrolu řešení ve svém řešení konektoru v kroku 1.

  3. Exportujte řešení konektoru.

  4. Vytvořte tok (testování) pomocí nově vytvořeného vlastního konektoru a přidejte tok do řešení.

  5. Exportujte řešení toku.

  6. Vytvořte balíček s řešeními z kroků 3 a 5.

  7. Vytvořte soubor intro.md.

  8. Vytvořte konečný balíček jako soubor zip, který je v následujícím formátu:

    Snímek obrazovky se složkami a soubory v souboru zip pro certifikovaný konektor, který má být certifikován.

  9. Nahrajte balíček do objektu blob úložiště a vygenerujte adresu URL SAS. Ujistěte se, že váš SAS URI je platný alespoň 15 dní.

  10. Odešlete balíček do Partnerského centra.

Zabalení vlastního konektoru a pluginu k certifikaci

  1. Postupujte podle kroků 1 až 5 v tématu Zabalení vlastního konektoru a odeslání k certifikaci v tomto článku.

  2. Vytvořte plugin na portálu Microsoft Copilot Studio a exportujte ho jako řešení.

  3. Vytvořte balíček z následujícího:

  4. Vytvořte soubor intro.md.

  5. Vytvořte konečný balíček jako soubor zip, který je v následujícím formátu.

    Snímek obrazovky se složkami a soubory v souboru zip pro certifikovaný konektor a plugin, který má být certifikován.

  6. Nahrajte balíček do objektu blob úložiště a vygenerujte adresu URL SAS. Ujistěte se, že váš SAS URI je platný alespoň 15 dní.

  7. Odešlete balíček do Partnerského centra.

Zabalení existujícího certifikovaného konektoru a pluginu k certifikaci

  1. Vytvořte řešení v Power Automate a přidejte do něj již certifikovaný konektor.

  2. Postupujte podle kroků 2 až 4 v tématu Zabalení vlastního konektoru a odeslání k certifikaci v tomto článku.

  3. Vytvořte plugin na portálu Copilot Studio a exportujte ho jako řešení.

  4. Exportujte plugin jako řešení.

  5. Vytvořte balíček z následujícího:

  6. Vytvořte soubor intro.md.

  7. Vytvořte konečný balíček jako soubor zip, který je v následujícím formátu.

    Snímek obrazovky se složkami a soubory v souboru zip pro existující certifikovaný konektor a plugin, který má být certifikován.

  8. Nahrajte balíček do objektu blob úložiště a vygenerujte adresu URL SAS. Ujistěte se, že váš SAS URI je platný alespoň 15 dní.

  9. Odešlete balíček do Partnerského centra.

Ověření vydavatelé i nezávislí vydavatelé stahují openapidefinition.json ve svých artefaktech. Budete muset nastavit IconBrandColor v tomto souboru.

  • Ověření majitelé stránek: Nastavte iconBrandColor na barvu vaší značky v souboru openapidefinition.
  • Nezávislí vydavatelé: Nastavte iconBrandColor na „#da3b01“ v souboru openapidefinition.
    Snímek obrazovky živé oranžové (da3b01) ikony.

Vytvořte artefakt intro.md.

Soubor intro.md je nezbytný jak pro nezávislé vydavatele, tak pro ověřené vydavatele. Musíte vytvořit soubor intro.md, abyste zdokumentovali funkce a funkčnost vašeho konektoru. Příklad dokumentace, kterou je třeba zahrnout, naleznete v části Příklad souboru Readme.md. Chcete-li se dozvědět o psaní souboru intro.md, podívejte se na další soubory intro.md (také označované jako soubory Readme.md) ve svém úložišti GitHub.

Pokud jste nezávislý vydavatel a váš konektor používá protokol OAuth, nezapomeňte uvést pokyny, jak získat přihlašovací údaje.

Tip

Známé problémy a omezení je skvělá sekce, kterou je třeba udržovat, aby vaši uživatelé měli aktuální informace.

Krok 7: Ověřte strukturu balíčku

Ověřovací skript balíčku ověří strukturu balíčku a pomůže vám vygenerovat balíček v přijatelném formátu pro certifikaci. Stáhněte si skript validátoru balíčků pomocí tohoto odkazu: ConnectorPackageValidator.ps1.

Chcete-li skript spustit, postupujte takto:

  1. Otevřete Windows PowerShell v režimu správce.

    Snímek obrazovky prostředí Windows PowerShell v režimu správce.

  2. Změňte umístění jednotky zadáním cd /.

    Následující příklad používá C:\.

    Snímek obrazovky se syntaxí pro změnu jednotky.

  3. Přejděte na cestu, ze které jste stáhli skript validátoru balíčku.

    Pokud je například cesta C:\Users\user01\Downloads, zadáte cd .\Users\user01\Downloads\.

    Snímek obrazovky se syntaxí pro změnu cesty.

  4. Nastavte zásady provádění na neomezené zadáním následujícího příkazu:

    Set-ExecutionPolicy -ExecutionPolicy Unrestricted

    Snímek obrazovky se syntaxí pro nastavení zásad provádění.

    Tento příkaz umožňuje spouštění prostředí PowerShell bez jakéhokoli omezení.

  5. Potvrďte zadání zadáním Y, což znamená Ano.

  6. Spusťte ConnectorPackageValidator.ps1 podle následujících kroků:

    1. Zadejte cestu k souboru zip, který obsahuje balíček konektoru.
    2. Určete, zda je povolena modul plug-in s AI.

    Jak ukazuje následující příklad, prvním argumentem je platná cesta k souboru zip, který obsahuje balíček. Druhým argumentem je yes/y k označení modul plug-in s AI je povoleno, nebo no/n k označení, že je zakázáno.

    Snímek obrazovky se syntaxí pro spuštění ConnectorPackageValidator.ps1.

    Pokud je struktura balíčku správná, zobrazí se následující zpráva o úspěchu:

    Snímek obrazovky se zprávou o úspěchu.

    Pokud se vyskytne problém se strukturou balíčku, skript poskytne podrobnosti o problému tím, že detekuje a zvýrazní vady ve struktuře balíčku.

    Snímek obrazovky s podrobnostmi o problému.

Krok 8: Odeslání vašeho konektoru nebo pluginu k certifikaci

Během procesu odesílání vydáváte konektoru nebo plugin jako opensourcový do našeho Úložiště konektorů Microsoft Power Platform.

  1. (Pro nezávislé vydavatele) Chcete-li odeslat balíček společnosti Microsoft k certifikaci, postupujte podle pokynů v Proces certifikace nezávislého vydavatele.

  2. (Pro ověřené vydavatele) Chcete-li odeslat balíček společnosti Microsoft k certifikaci do Partnerského centra, postupujte podle pokynů v Proces certifikace ověřeného vydavatele.

    Pokud jste ověřený vydavatel a používáte vlastní kód, budete muset odeslat soubor script.csx.

    Pokud má váš konektor protokol OAuth, zadejte ID klienta a tajný klíč v Partnerském centru. Chcete-li aktualizovat aplikaci, získejte také název API z žádosti o odeslání konektoru.

    Jako součást odeslání společnost Microsoft certifikuje váš konektor nebo plugin. Pokud potřebujete vyřešit chyby se swaggerem, přejděte do části Oprava chyb nástroje Swagger Validator.

Kontrolní seznam před odesláním

Před přechodem na krok Odešlete svůj konektor k certifikaci Microsoft, se ujistěte, že:

Tip

  • Vytvořte videa na YouTube, blogy nebo jiný obsah pro sdílení ukázek nebo snímků obrazovky, jak začít s konektorem nebo pluginem.
  • Zahrňte odkazy do souboru intro.md, abychom ho mohli přidat do našich dokumentů.
  • Přidejte popisky do vašeho souboru swagger, aby vaši uživatelé byli úspěšnější.

Další krok