Sdílet prostřednictvím

Seznámení s osvědčenými postupy pro pole řetězců

  • Článek

Následující článek obsahuje obecné pokyny pro pole řetězců v konektoru pro Power Automate, Power Apps a Azure Logic Apps.

Informace o konektoru

Každý konektor by měl mít název, což je název konektoru, a popis, který obecně popisuje konektor. Tyto informace by měly být uvedeny v polích title and description fields under the info section v definici OpenAPI (v souboru apiDefinition.swagger.json).

U názvů a popisů konektoru musíte dodržet následující pokyny:

  • Název konektoru může mít maximálně 30 znaků.
  • Název ani popis konektoru nesmí obsahovat slovo API.
  • Název ani popis konektoru nesmí odkazovat na produkt Power Platform ani na produkt, pro který nevlastníte rozhraní API back-endu.

Vyšší standard pokynů pro pole názvu a popisu pro certifikované konektory najdete tady a měl by se používat jako osvědčený postup.

Operace

Každá cesta a příkaz v definici OpenAPI odpovídá jedné operaci. Odpovídající popisy operací s využitím jednotlivých řetězců/značek pomáhají koncovým uživatelům ve správném využití. Některá pole řetězců pro operaci jsou:

  • summary: Toto se zobrazí jako název operace.

    • Velikost písmen: Věta
    • Poznámky:
      • V názvu nesmí být lomítko („/“).
      • Délka nesmí přesáhnout 80 znaků.
      • Nesmí končit nealfanumerickým znakem, včetně interpunkce nebo mezery.

  • description: Tento údaj se zobrazí jako popis operace při výběru informačního tlačítka Snímek obrazovky s informačním tlačítkem., jak je vidět na následujícím obrázku.

    • Velikost písmen: Věta.
    • Poznámky: Pište krátké řetězce, které se vejdou do textového pole. Není vyžadována tečka, pokud je tam jediné slovo.

  • operationId: Toto je jedinečný identifikátor přidružený k operaci.

    • Velikost písmen: První písmeno slova velké (bez mezer a interpunkce).
    • Poznámky: Určeno k vyjádření významu operace, například GetContacts nebo CreateContact.

    Následující obrázek ukazuje, jak se pole summary—Odeslat e-mail a description—Tato operace odešle e-mailovou zprávu zobrazí při vytváření pracovního postupu.

    Snímek obrazovky ukazující, jak se pole souhrnu a popisu zobrazí.

Triggery versus akce

Trigger spustí pracovní postup nebo proces. Příklady: „Spustit pracovní postup každé pondělí v 15:00“, „Při vytvoření projektu“ atd.

Pole souhrnu a popisu spouštění by měla být čitelná uživatelům a měla by mít sémantický význam. Trigger summary má obvykle formát: "Když __________________".

Příklad:

Trigger Souhrn
Vytvoření Při vytvoření úkolu
Aktualizace Při aktualizaci úkolu
Odstraněno Při odstranění úkolu

Trigger description je obvykle ve formátu: "Tato operace se spustí, když _______________"

Příklad:

  • Tato operace se spustí, když je přidán nový úkol.

Akce je úkol, který je potřeba dokončit v rámci vašeho pracovního postupu, jako je třeba Odeslat e-mail, Aktualizovat řádek, Odeslat oznámení atd. Několik příkladů akce summary je uvedeno níže:

Akce Souhrn
Vytvoření Vytvoření nového úkolu
Přečíst Získat úkol podle ID
Aktualizace Aktualizace objektu
Odstraněno Odstranění objektu
Seznam Seznam všech objektů

Parametry

Každá operace (trigger i akce) má parametry, které uživatel zadává jako vstup. Některá důležitá pole řetězce pro parametr jsou:

  • x-ms-summary: Zobrazí se jako název parametru.

    • Případ: název
    • Poznámky: Může mít maximálně 80 znaků

  • description: Toto se zobrazí jako popis parametru ve vstupním poli.

    • Případ: Věta
    • Poznámky: Pište krátké řetězce, které se vejdou do textového pole. Není vyžadována tečka, pokud je tam jediné slovo.

    Na následujícím obrázku má zvýrazněný parametr v poli x-ms-summary hodnotu Subject (Předmět) a v poli description hodnotu Specify the subject of the mail (Zadejte předmět e-mailu).

    Snímek obrazovky, který ukazuje hodnoty parametrů x-ms-summary a description v rozhraní.

Reakce

Každá operace má odpověď, kterou se dá později v pracovním postupu použít jako vstup pro následnou operaci. Výsledné schéma se skládá z více vlastností. Některá důležitá pole řetězce pro jednotlivé vlastnosti jsou:

  • x-ms-summary: Zobrazí se jako název vlastnosti výsledku.

    • Případ: název
    • Poznámky: Použijte krátký název.

  • description: Zobrazí se jako popis vlastnosti result.

    • Případ: Věta
    • Poznámky: Měl by být krátký a stručný s tečkou na konci.

    Na obrázku níže se při pokusu o přidání dynamického obsahu do jedné z následujících operací v pracovním postupu zobrazí schéma výsledků z operace „Ručně spustit tok“. V tomto příkladu pole x-ms-summary obsahuje text User email (E-mail uživatele) a text pod ním je pole description pro vlastnost v odpovědi na operaci Manually trigger a flow (Ručně aktivovat tok).

odpověď

Několik důležitých poznámek, které byste měli pro pole summary/x-ms-summary a description obecně vzít v úvahu:

  • Text shrnutí a popisu by neměly být stejné.
  • Pole description by mělo sloužit k tomu, aby uživateli poskytlo další informace, jako je třeba výstupní formát nebo objekt, se kterým příslušná vlastnost souvisí. Příklad: summary : ID, description: ID uživatele.
  • U objektu s vnořenými hodnotami se pole x-ms-summary názvu nadřazeného objektu připojí k podřízenému prvku.

x-ms-visibility

Určuje prioritu viditelnosti entity. Pokud viditelnost není zadaná, předpokládá se normální viditelnost (normal). Možné hodnoty jsou important, advanced nebo internal. Entity označené jako interní se v uživatelském rozhraní nezobrazují.

Platí pro:

  • Operace
  • Parametry
  • Vlastnosti odpovědi

Příklad:

V uživatelském rozhraní se entity s označením „important“ zobrazí jako první, entity s označením „advanced“ budou skryté pod přepínačem (zvýrazněné) a entity s označením „internal“ se nezobrazí. Následující obrázek je příkladem parametrů označených jako „důležité“, které se zobrazují ve výchozím nastavení. Zobrazuje také parametry označené jako "pokročilé", které se zobrazují po výběru tlačítka Zobrazit pokročilé možnosti.

Snímek obrazovky s rozevíracím seznamem pokročilých možností.

Snímek obrazovky, který ukazuje rozbalené skryté rozšířené možnosti.

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.