Hulp met connectortekenreeksen

Het volgende onderwerp bevat algemene richtlijnen voor tekenreeksvelden binnen een connector voor Power Automate, Power Apps en Logic Apps.

Connectorgegevens

Elke connector moet een titel hebben (de naam van de connector) en een beschrijving die de connector in het algemeen beschrijft. Deze gegevens worden opgenomen in de velden title en description in het gedeelte info van de OpenAPI-definitie (in het bestand apiDefinition.swagger.json).

De volgende richtlijnen moeten minimaal worden gevolgd voor de titel en beschrijving van connectors:

• De naam van de connector mag uit maximaal 30 tekens bestaan.
• De titel en beschrijving van de connector mogen niet het woord API bevatten.
• De titel en beschrijving van de connector mogen niet verwijzen naar een Power Platform-product of een product met back-end-API's waarvan u geen eigenaar bent.

U vindt hier een hogere normen voor richtlijnen voor de titel- en beschrijvingsvelden van gecertificeerde connectors. Deze moeten worden gebruikt als best practices.

Bewerkingen

Elk pad en elke term in de OpenAPI-definitie komt overeen met een bewerking. Als u de bewerking adequaat beschrijft aan de hand van alle tekenreeksen/tags hieronder, is de eindgebruiker beter in staat de bewerking op de juiste manier te gebruiken. Enkele van de tekenreeksvelden voor een bewerking zijn:

• summary: deze wordt weergegeven als de naam van de bewerking.

  • Case: Zin
  • Opmerkingen:
    • De naam mag geen slash ('/') bevatten.
    • De naam mag niet langer zijn dan 80 tekens.
    • De naam mag niet eindigen met een niet-alfanumeriek teken, waaronder leestekens of een spatie.

• description: hier wordt de beschrijving van de bewerking weergegeven nadat de informatieknop is geselecteerd (zie de onderstaande afbeelding).

  • Case: Zin
  • Opmerkingen: houd het kort zodat de waarde in het tekstvak past. Geen punt vereist bij enkel woord.

• operationId: dit is de unieke id die aan de bewerking is gekoppeld.

  • Case: Camel
  • Opmerkingen: bedoeld om aan te geven wat de bewerking inhoudt, zoals GetContacts of CreateContact.

  In de onderstaande afbeelding ziet u hoe de inhoud van het veld summary ('Een e-mail verzenden') en het veld description ('Via deze bewerking wordt een e-mailbericht verzonden') in de gebruikersinterface worden weergegeven bij het maken van een werkstroom.

  

Triggers versus acties

Een trigger start een werkstroom of proces. Bijvoorbeeld: 'Begin elke maandag om 3 uur een werkstroom', 'Wanneer een object wordt gemaakt' enzovoorts.

De velden voor triggersamenvattingen en beschrijvingen moeten voor mensen leesbaar zijn en een semantische betekenis hebben. Trigger summary heeft meestal de indeling: "Wanneer een __________________".

Voorbeeld:

Trigger description heeft meestal de indeling: 'Deze bewerking wordt geactiveerd wanneer _______________'

Voorbeeld:

• Deze bewerking wordt geactiveerd wanneer een nieuwe taak wordt toegevoegd.

Een actie is een taak die wordt uitgevoerd binnen de werkstroom, zoals 'Een e-mail verzenden', 'Een rij bijwerken', 'Een melding verzenden' enzovoorts. Een paar voorbeelden voor actie summary worden hieronder gegeven:

Parameters

Elke bewerking (zowel een trigger als een actie) heeft parameters die de gebruiker opgeeft als invoer. Enkele van de belangrijke tekenreeksvelden voor een parameter zijn:

• x-ms-summary: deze wordt weergegeven als de parameternaam.

  • Case: Titel
  • Opmerking' heeft een maximumlengte van 80 tekens

• description: dit wordt weergegeven als de parameterbeschrijving in het invoervak.

  • Case: Zin
  • Opmerkingen: houd het kort zodat de waarde in het tekstvak past. Geen punt vereist bij enkel woord.

  In de onderstaande afbeelding is 'Onderwerp' de waarde voor het veld x-ms-summary van de gemarkeerde parameter en 'Geef het onderwerp van de e-mail op' de waarde van het veld description.

  

De respons

Elke bewerking heeft een antwoord, dat verderop in de werkstroom kan dienen als invoer voor een volgende bewerking. Het resultatenschema bestaat uit meerdere eigenschappen. Enkele van de belangrijke tekenreeksvelden voor elke eigenschap zijn:

• x-ms-summary: deze wordt weergegeven als de eigenschapnaam voor het resultaat.

  • Case: Titel
  • Opmerkingen: gebruik een korte naam.

• description: dit wordt weergegeven als de beschrijving voor de resultaateigenschap.

  • Case: Zin
  • Opmerkingen: moet kort en beknopt zijn, met een punt aan het einde.

  In de onderstaande afbeelding wordt het resultaatschema van de bewerking "Handmatig een stroom activeren" weergegeven wanneer u probeert dynamische inhoud toe te voegen aan een van de volgende bewerkingen in de werkstroom. 'E-mail gebruiker' is hier de x-ms-summary en de tekst daaronder de description van een eigenschap in het antwoord van de bewerking 'Handmatig een stroom activeren'.

Dit zijn enkele belangrijke punten waar u rekening mee moet houden bij het definiëren van de velden summary/x-ms-summary en description:

• Samenvatting en beschrijvingstekst mogen niet hetzelfde zijn.
• De tekst in het veld description moet de gebruiker aanvullende informatie bieden, zoals de indeling van de uitvoer of het object waaraan de eigenschap is gerelateerd. Bijvoorbeeld: summary: Id, description: Id van gebruiker.
• In het geval van een object met geneste waarden wordt de x-ms-summary van de bovenliggende naam toegevoegd aan het onderliggende element.

x-ms-visibility

Hiermee wordt de zichtbaarheidsprioriteit van de entiteit bepaald. Als er geen zichtbaarheid wordt opgegeven, wordt dit geïnterpreteerd als 'normale' zichtbaarheid. De mogelijke waarden zijn 'important', 'advanced' en 'internal'. Entiteiten die zijn gemarkeerd als 'internal', worden niet weergegeven in de gebruikersinterface.

Van toepassing op:

• Bewerkingen
• Parameters
• Responseigenschappen

Voorbeeld: in de gebruikersinterface worden als "important" gemarkeerde entiteiten doorgaans als eerste weergegeven, zijn als "advanced" gemarkeerde elementen verborgen onder een wisselknop (gemarkeerd) en worden als "internal" gemarkeerde elementen niet weergegeven. Zoals bijvoorbeeld wordt weergegeven in de onderstaande afbeelding, worden parameters die zijn gemarkeerd als "important" standaard weergegeven en worden parameters die zijn gemarkeerd als "advanced" weergegeven nadat op de knop "Geavanceerde opties weergeven" is geklikt.