Freigeben über

Best Practices bei Zeichenfolgenfeldern

  • Artikel

Der folgende Artikel enthält eine allgemeine Anleitung für Zeichenfolgenfelder innerhalb eines Connectors für Power Automate, Power Apps und Azure Logic Apps.

Konnektorinformationen

Jeder Konnektor sollte einen Titel haben, der den Namen des Konnektors darstellt, und eine Beschreibung, die den Konnektor im Allgemeinen beschreibt. Diese Informationen müssen in den Feldern Titel und Beschreibung unter dem Abschnitt Info in der OpenAPI-Definition (in der Datei „apiDefinition.swagger.json“) angegeben werden.

Für Connectortitel und -beschreibungen müssen mindestens die folgenden Richtlinien befolgt werden:

  • Der Connectortitel darf maximal 30 Zeichen lang sein.
  • Connectortitel und -beschreibung dürfen das Wort API nicht enthalten.
  • Connectortitel und -beschreibung dürfen nicht auf ein Power Platform-Produkt oder ein Produkt verweisen, für das Sie die Back-End-APIs nicht besitzen.

Ein höherer Standard von Richtlinien für Titel- und Beschreibungsfelder, die für zertifizierte Connectors erzwungen werden, finden Sie hier. Sie sollten sie als Best Practices verwenden.

Vorgänge

Jeder Pfad und jedes Verb in der OpenAPI-Definition entspricht einem Vorgang. Eine korrekte Beschreibung des Vorgangs mit jeder/m der folgenden Zeichenfolgen/Tags hilft dem Endbenutzer bei der richtigen Anwendung. Einige der String-Felder für eine Operation sind: Einige der String-Felder für eine Operation sind::

  • summary: Dies wird als Name der Operation angezeigt.

    • Fall: Satz
    • Hinweise:
      • Der Name sollte keinen Schrägstrich („/“) enthalten.
      • Es darf nicht länger als 80 Zeichen sein.
      • Er darf nicht mit einem nicht alphanumerischen Zeichen enden, einschließlich Interpunktions- oder Leerzeichen.

  • Beschreibung: Dies wird als Vorgangsbeschreibung angezeigt, wenn Sie die Informationsschaltfläche auswählen Screenshot, der die Informationsschaltfläche zeigt., wie im folgenden Bild gezeigt.

    • Fall: Satz.
    • Anmerkungen: Kurz halten, damit alles in das Textfeld passt. Bei einem einzelnen Wort ist kein Punkt erforderlich.

  • operationId: Dies ist die eindeutige ID, die mit dem Vorgang verbunden ist.

    • Fall: Camel (keine Leerzeichen oder Satzzeichen).
    • Anmerkungen: Dient dazu, die Bedeutung des Vorgangs zu vermitteln, wie z.B. GetContacts oder CreateContact.

    Das folgende Bild zeigt, wie Sie summary—E-Mail senden, und description—Dieser Vorgang schickt eine E-Mail-Nachricht Felder angezeigt werden, während Sie einen Workflow erstellen.

    Screenshot, der zeigt, wie die Zusammenfassungs- und Beschreibungsfelder angezeigt werden.

Trigger im Vergleich zu Aktionen

Ein Trigger startet einen Workflow oder Prozess. Beispiele: „Einen Workflow jeden Montag um 3.00 Uhr starten“, „Wenn ein Objekt erstellt wird“ usw.

Trigger-Zusammenfassungs- und Beschreibungsfelder sollten für den Menschen lesbar sein und eine semantische Bedeutung haben. Auslöser Zusammenfassung ist normalerweise im Format: "Wenn __________________________".

Beispiel:

Trigger Übersicht
Erstellen Wenn eine Aufgabe erstellt wird
Update Wenn eine Aufgabe aktualisiert wird
gelöscht wird Wenn eine Aufgabe gelöscht wird

Auslöser Beschreibung ist normalerweise im Format: "Diese Operation wird ausgelöst, wenn _______________"

Beispiel:

  • Diese Operation wird ausgelöst, wenn eine neue Aufgabe hinzugefügt wird.

Eine Aktion ist eine Aufgabe, die innerhalb des Workflows abgeschlossen werden muss, z. B. „E-Mail senden“, „Zeile aktualisieren“, „Benachrichtigung senden“ usw. Im Folgenden werden einige Beispiele für Aktionen Zusammenfassung gegeben:

Aktion Übersicht
Erstellen Neue Aufgabe erstellen
Gelesen Aufgabe nach ID abrufen
Update Objekt aktualisieren
gelöscht wird Objekt löschen
Auflisten Alle Objekte auflisten

Parameter

Jeder Vorgang (ob Auslöser oder Aktion) hat Parameter, die der Benutzer als Eingabe bereitstellt. Einige der wichtigen String-Felder für einen Parameter sind:

  • x-ms-summary: Dies wird als Parametername angezeigt.

    • Fall: Titel
    • Anmerkungen: Hat ein Limit von 80 Zeichen

  • Beschreibung: Dies wird als Parameterbeschreibung im Eingabefeld angezeigt.

    • Fall: Satz
    • Anmerkungen: Kurz halten, damit alles in das Textfeld passt. Bei einem einzelnen Wort ist kein Punkt erforderlich.

    In der Abbildung unten ist für den Parameter „Betreff“ als Wert für das Feld x-ms-summary und „Geben Sie den Betreff der E-Mail an.“ für das Feld Beschreibung hervorgehoben.

    Screenshot, der die x-ms-summary- und description-Parameterwerte in der Benutzeroberfläche zeigt.

Response

Jeder Vorgang hat eine Antwort, die später im Workflow als Eingabe für einen nachfolgenden Vorgang verwendet werden kann. Das Ergebnisschema besteht aus mehreren Eigenschaften. Einige der wichtigen Zeichenfolgenfelder für jede Eigenschaft sind:

  • x-ms-summary: Dies wird als Name der Ergebniseigenschaft angezeigt.

    • Fall: Titel
    • Anmerkungen: Verwenden Sie einen kurzen Namen.

  • description: Dies wird als Beschreibung für die Ergebnis-Eigenschaft angezeigt.

    • Fall: Satz
    • Anmerkungen: Kurz halten. Sollte kurz und prägnant sein, mit einem Punkt am Ende

    In der unten gezeigten Abbildung wird das Ergebnisschema der Operation "Manuelles Auslösen eines Flusses" angezeigt, wenn Sie versuchen, dynamischen Inhalt in einer der nachfolgenden Operationen im Workflow hinzuzufügen. Hier ist „Benutzer-E-Mail“ der Wert des Felds x-ms-summary und der Text darunter ist die Beschreibung für eine Eigenschaft in der Antwort auf den Vorgang „Flow manuell auslösen“.

Antwort

Einige wichtige Hinweise sind bei den Feldern „Zusammenfassung“/„x-ms-summary“ und „Beschreibung“ generell zu beachten:

  • Der Zusammenfassungs- und Beschreibungstext sollten nicht identisch sein.
  • Die Beschreibung sollte verwendet werden, um dem Benutzer zusätzliche Informationen wie das Ausgabeformat oder das Objekt, auf das sich die Eigenschaft bezieht, zur Verfügung zu stellen. Zum Beispiel: Zusammenfassung: ID, Beschreibung: Benutzer-ID.
  • Bei einem Objekt mit geschachtelten Werten wird der Wert im Feld x-ms-summary des übergeordneten Namens an das untergeordnete Element angefügt.

x-ms-visibility

Bestimmt die Sichtbarkeitspriorität der Entität. Wenn keine Sichtbarkeit angegeben ist, gilt die „normale“ Sichtbarkeit. Die möglichen Werte sind „wichtig“, „erweitert“ und „intern“. Entitäten, die als „intern“ markiert sind, werden nicht auf der Benutzeroberfläche angezeigt.

Gilt für:

  • Vorgänge
  • Parameter
  • Antworteigenschaften

Beispiel:

Auf der Benutzeroberfläche werden als „wichtig“ markierte Entitäten in der Regel zuerst angezeigt, als „erweitert“ markierte Elemente sind hinter einer Umschaltfläche ausgeblendet (hervorgehoben), und als „intern“ markierte Elemente werden nicht angezeigt. Das folgende Bild ist ein Beispiel für Parameter, die als „wichtig“ gekennzeichnet sind und standardmäßig angezeigt werden. Es zeigt auch als „erweitert“ markierte Parameter, die nach Auswahl der Schaltfläche Erweiterte Optionen anzeigen angezeigt werden.

Screenshot, der eine Dropdown-Liste für erweiterte Optionen zeigt.

Screenshot mit den erweiterten versteckten, erweiterten Optionen.

Feedback senden

Wir freuen uns sehr über Feedback zu Problemen mit unserer Connector-Plattform oder neuen Feature-Ideen. Wenn Sie Feedback geben möchten, gehen Sie zu Probleme melden oder Hilfe zu Connectors und wählen Sie einen Feedbacktyp aus.