Delen via

Best practices voor tekenreeksvelden

  • Artikel

Het volgende artikel bevat algemene richtlijnen voor tekenreeksvelden in een connector voor Power Automate, Power Apps en Azure 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 norm 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 code mag maximaal 80 tekens lang zijn.
      • De naam mag niet eindigen met een niet-alfanumeriek teken, waaronder leestekens of een spatie.

  • description: dit wordt weergegeven als de bewerkingsbeschrijving bij het selecteren van de informatieknop Schermopname met de informatieknop., zoals in de volgende afbeelding wordt getoond.

    • Case: Zin.
    • Opmerkingen: houd het kort zodat de waarde in het tekstvak past. U hoeft geen punt te gebruiken voor één woord.

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

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

    In de volgende afbeelding ziet u hoe de velden summary—Een e-mail verzenden en description—Via deze bewerking wordt een e-mailbericht verzonden worden weergegeven bij het maken van een werkstroom.

    Schermopname die laat zien hoe de velden voor samenvatting en beschrijving worden weergegeven.

Triggers versus acties

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

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:

Activator Overzicht
Create Wanneer een taak wordt gemaakt
Bijwerken Wanneer een taak wordt bijgewerkt
Verwijderd Wanneer een taak wordt verwijderd

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:

Actie Overzicht
Create Nieuwe taak maken
Read Taak per id ophalen
Bijwerken Object bijwerken
Verwijderd Object verwijderen
Weergeven Alle objecten in lijst weergeven

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: deze heeft een maximumlengte van 80 tekens

  • description: Dit dordt weergegeven als de parameterbeschrijving in het invoervak.

    • Case: Zin
    • Opmerkingen: houd het kort zodat de waarde in het tekstvak past. U hoeft geen punt te gebruiken voor één 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.

    Schermopname die de parameterwaarden x-ms-summary en description in de interface laat zien.

Respons

Elke bewerking heeft een antwoord, dat verderop in de werkstroom kan dienen als invoer voor een volgende bewerking. Het resultaatschema 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. 'User email' is hier de x-ms-summary en de tekst daaronder is de description voor een eigenschap in het antwoord van de bewerking 'Handmatig een stroom activeren'.

respons

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

  • De samenvattings- 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.
  • Voor 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 'intern', worden niet weergegeven in de gebruikersinterface.

Van toepassing op:

  • Bewerkingen
  • Parameters
  • Responseigenschappen

Voorbeeld:

In de gebruikersinterface worden als 'important' gemarkeerde entiteiten als eerste weergegeven, zijn als 'advanced' gemarkeerde elementen verborgen onder een wisselknop (zie de markering in de onderstaande afbeelding) en worden als 'internal' gemarkeerde elementen niet weergegeven. De volgende afbeelding is een voorbeeld van als 'important' gemarkeerde parameters die standaard worden weergegeven. Ook ziet u parameters die zijn gemarkeerd als 'advanced' die worden weergegeven na het selecteren van de knop Geavanceerde opties weergeven.

Schermopname met een vervolgkeuzelijst voor geavanceerde opties.

Schermopname met de uitgebreide verborgen geavanceerde opties.

Feedback geven

We stellen feedback over problemen met ons connectorplatform of ideeën voor nieuwe functies zeer op prijs. Om feedback te geven, gaat u naar Problemen melden of hulp krijgen met connectoren en selecteer uw feedbacktype.