Condividi tramite

Informazioni sulle procedure consigliate per i campi stringa

  • Articolo

L'articolo seguente contiene indicazioni generali per i campi stringa all'interno di un connettore per Power Automate, Power Apps e App per la logica di Azure.

Informazioni sul connettore

Ogni connettore deve avere un titolo, che è il nome del connettore, e una descrizione che descrive il connettore in generale. Queste informazioni devono essere specificate nei campi title e description nella sezione info della definizione OpenAPI, nel file apiDefinition.swagger.json.

È necessario seguire almeno le linee guida seguenti per le descrizioni e i titoli dei connettori:

  • Il titolo del connettore non può essere composto da più di 30 caratteri.
  • Il titolo e la descrizione del connettore non possono includere la parola API.
  • Il titolo e la descrizione del connettore non possono fare riferimento a un prodotto Power Platform o a un prodotto per cui non si è proprietari delle API back-end.

Per i connettori certificati, qui sono disponibili linee guida per i campi di titolo e descrizione basati su standard più elevati, da applicare come procedure consigliate.

Operazioni

Ogni percorso e verbo della definizione OpenAPI corrisponde a un'operazione. Per consentire all'utente finale di usare correttamente l'operazione, è opportuno descriverla con le stringhe o i tag seguenti. Alcuni dei campi di stringa per un'operazione sono:

  • riepilogo: questo campo verrà visualizzato come nome dell'operazione.

    • Maiuscole/Minuscole: frase
    • Note:
      • Non è possibile utilizzare la barra ("/") nel nome.
      • Non può superare 80 caratteri.
      • Non deve terminare con un carattere non alfanumerico, inclusi segni di punteggiatura o spazi.

  • descrizione: apparirà come descrizione dell'operazione quando si seleziona il pulsante delle informazioni Screenshot che mostra il pulsante delle informazioni., come indicato nell'immagine seguente.

    • Maiuscole/Minuscole: frase.
    • Note: mantieni il testo breve affinché rientri nella casella di testo. Nessun periodo richiesto se c'è una sola parola.

  • operationId: l'ID univoco associato all'operazione.

    • Maiuscole/Minuscole: notazione Camel (senza spazi o punteggiatura).
    • Note: viene usato per comunicare il significato dell'operazione, ad esempio GetContacts o CreateContact.

    L'immagine seguente mostra in che modo vengono visualizzati i campi summary (Invia un messaggio e-mail) e description (Questa operazione invia un messaggio e-mail) nell'interfaccia utente durante la creazione di un flusso di lavoro.

    Screenshot che mostra come appariranno i campi di riepilogo e descrizione.

Trigger e azioni

Un trigger avvia un flusso di lavoro o un processo. ad esempio "Avvia un flusso di lavoro ogni lunedì alle 3", "Quando viene creato un oggetto" e così via.

I campi di riepilogo e descrizione dei trigger devono essere leggibili e avere un significato semantico. Il campo riepilogo del trigger è di solito nel formato: "Quando un __________________".

Esempio:

Trigger Riepilogo
Creazione di Alla creazione di un'attività
Aggiornamento All'aggiornamento di un'attività
Eliminati All'eliminazione di un'attività

Il campo descrizione del trigger di solito è nel formato: "Questa operazione si attiva quando _______________"

Esempio:

  • Questa operazione si attiva quando viene aggiunta una nuova attività.

Un'azione è un'attività da completare nel flusso di lavoro, ad esempio "Invia un messaggio e-mail", "Aggiorna una riga", "Invia una notifica" e così via. Alcuni esempi di riepilogo dell'azione sono riportati di seguito:

Azione Riepilogo
Creazione di Crea nuova attività
Letta Recupera attività per ID
Aggiornamento Aggiorna oggetto
Eliminati Elimina oggetto
Elenco Elenca tutti gli oggetti

Parametri

A ogni operazione (trigger o azione) sono associati parametri che l'utente specifica come input. Alcuni dei campi di stringa importanti per un parametro sono:

  • x-ms-summary: questo campo verrà visualizzato come nome del parametro.

    • Maiuscole/Minuscole: titolo
    • Note: ha un limite di 80 caratteri

  • descrizione: questo apparirà come la descrizione del parametro all'interno della casella di input.

    • Maiuscole/Minuscole: frase
    • Note: mantieni il testo breve per farlo rientrare nella casella di testo. Nessun periodo richiesto se c'è una sola parola.

    Nell'immagine seguente il valore del parametro evidenziato è "Oggetto" per il campo x-ms-summary e "Specifica l'oggetto del messaggio e-mail"per description.

    Screenshot che mostra i valori dei parametri x-ms-summary e description nell'interfaccia.

Risposta

Per ogni operazione è disponibile una risposta che può essere usata più avanti nel flusso di lavoro come input di un'operazione successiva. Lo schema dei risultati è composto da più proprietà. Alcuni dei campi di stringa importanti per ogni proprietà sono:

  • x-ms-summary: questo campo verrà visualizzato come nome della proprietà del risultato.

    • Maiuscole/Minuscole: titolo
    • Note: utilizza un nome breve.

  • descrizione: questo campo verrà visualizzato come descrizione per la proprietà del risultato.

    • Maiuscole/Minuscole: frase
    • Note: deve essere breve e concisa, con un punto alla fine.

    Nell'immagine mostrata di seguito, lo schema del risultato dell'operazione "Attiva manualmente un flusso" viene visualizzato quando tenti di aggiungere contenuto dinamico a una delle operazioni successive nel flusso di lavoro. In questo caso, "Indirizzo di posta elettronica dell'utente" è il valore di x-ms-summary e il testo al di sotto è il valore di description per una proprietà nella risposta dell'operazione "Attiva un flusso manualmente".

risposta

Ecco alcune note importanti da considerare a livello generale per i campi summary/x-ms-summary e description:

  • Riepilogo e testo descrittivo non dovrebbero essere gli stessi.
  • È consigliabile usare description per fornire informazioni aggiuntive all'utente, ad esempio il formato di output o l'oggetto cui è correlata la proprietà. AD esempio: riepilogo : ID, descrizione: ID utente.
  • Per un oggetto con valori annidati, il campo x-ms-summary del nome dell'elemento padre verrà aggiunto all'elemento figlio.

x-ms-visibility

Determina la priorità della visibilità dell'entità. Se non viene specificata alcuna visibilità, verrà usata quella normale. I valori possibili sono "important", "advanced" o "internal". Le entità contrassegnate come "internal" non vengono visualizzate nell'interfaccia utente.

Si applica a:

  • Operazioni
  • Parametri
  • Proprietà della risposta

Esempio:

Nell'interfaccia utente le entità contrassegnate come "important" vengono visualizzate per prime, quelle contrassegnate come "advanced" vengono nascoste sotto un interruttore (evidenziato) e quelle contrassegnate come "internal" non vengono visualizzate. L'immagine seguente è un esempio di parametri contrassegnati come "important" visualizzati per impostazione predefinita. Mostra anche i parametri contrassegnati come "advanced" visualizzati dopo aver selezionato il pulsante Mostra opzioni avanzate.

Screenshot che mostra un elenco a discesa per le opzioni avanzate.

Screenshot che mostra le opzioni avanzate nascoste espanse.

Inviare commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.