Estendere la definizione OpenAPI per un connettore personalizzato

Per creare connettori personalizzati per App per la logica di Azure, Microsoft Power Automate o Microsoft Power Apps, una delle opzioni disponibili consiste nel fornire un file di definizione OpenAPI, ovvero un documento leggibile dal computer e indipendente dal linguaggio che descrive le operazioni e i parametri dell'API. Oltre alla funzionalità predefinita di OpenAPI, è possibile includere anche delle estensioni di OpenAPI seguenti quando si creano connettori personalizzati per App per la logica di Azure e Power Automate:

• summary
• x-ms-summary
• description
• x-ms-visibility
• x-ms-api-annotation
• x-ms-operation-context
• x-ms-capabilities
• x-ms-trigger
• x-ms-trigger-hint
• x-ms-notification-content
• x-ms-notification-url
• x-ms-url-encoding
• x-ms-dynamic-values and x-ms-dynamic-list
• x-ms-dynamic-schema and x-ms-dynamic-properties

Le sezioni seguenti descrivono queste estensioni.

riepilogo

Specifica il titolo per l'azione (operazione).

Si applica a: Operazioni
Consigliato: usare la maiuscola a inizio frase per summary.
Esempio: "Quando viene aggiunto un evento al calendario" o "Invia un messaggio di posta elettronica"

"actions" {
  "Send_an_email": {
    /// Other action properties here...
    "summary": "Send an email",
    /// Other action properties here...
  }
},

x-ms-summary

Specifica il titolo per un'entità.

Si applica a: Parametri, schema di risposta
Consigliato: usare la maiuscola a inizio titolo per x-ms-summary.
Esempio: "ID calendario", "Oggetto", "Descrizione dell'evento"

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            /// Other parameters here...
            "x-ms-summary": "Subject",
            /// Other parameters here...
        }]
    }
},

descrizione

Specifica una spiegazione dettagliata delle funzionalità dell'operazione o del formato e della funzione di un'entità.

Si applica a: Operazioni, Parametri, Schema di risposta
Consigliato: usare la maiuscola a inizio frase per description.
Esempio: "Questa operazione viene attivata quando viene aggiunto un nuovo evento al calendario", "Specificare l'oggetto del messaggio di posta elettronica"

"actions" {
    "Send_an_email": {
        "description": "Specify the subject of the mail",
        /// Other action properties here...
    }
},

x-ms-visibility

Specifica la visibilità dell'entità verso l'utente.

Valori possibili: important, advanced e internal
Si applica a: Operazioni, Parametri, Schemi

• Le operazioni e i parametri contrassegnati di important vengono visualizzati per primi all'utente.
• Le operazioni e i parametri di advanced sono nascosti sotto un menu aggiuntivo.
• Le operazioni e i parametri di internal sono nascosti all'utente.

Nota

Per i parametri che sono internal e required, si devono fornire i valori predefiniti.

Esempio: i menu Vedi altri e Mostra opzioni avanzate nascondono le operazioni e i parametri di advanced.

"actions" {
    "Send_an_email": {
        /// Other action properties here...
        "parameters": [{
            "name": "Subject",
            "type": "string",
            "description": "Specify the subject of the mail",
            "x-ms-summary": "Subject",
            "x-ms-visibility": "important",
            /// Other parameter properties here...
        }]
        /// Other action properties here...
    }
},

x-ms-api-annotation

Si usa per il controllo delle versioni e la gestione del ciclo di vita di un'operazione.

Si applica a: Operazioni

• family—Stringa che indica la cartella della famiglia di operazioni.
• revision—Integer che indica il numero di revisione.
• replacement—Oggetto contenente le informazioni e le operazioni dell'API sostitutiva.

"x-ms-api-annotation": {
        "family": "ListFolder",
        "revision": 1,
        "replacement": {
          "api": "SftpWithSsh",
          "operationId": "ListFolder"
        }
      }

x-ms-operation-context

Si usa per simulare l'attivazione di un trigger per abilitare il test di un flusso dipendente dal trigger.

Si applica a: Operazioni

"x-ms-operation-context": {
        "simulate": {
          "operationId": "GetItems_V2",
          "parameters": {
            "$top": 1
          }
        }

x-ms-capabilities

A livello di connettore, si tratta di una panoramica delle funzionalità che offre, incluse operazioni specifiche.

Si applica a: Connettori

"x-ms-capabilities": {
  "testConnection": {
    "operationId": "GetCurrentUser"
  },
}

A livello di operazione, si usa per identificare che tale operazione supporta il caricamento in blocchi e/o le dimensioni statiche dei blocchi e può essere specificata dall'utente.

Si applica a: Operazioni

• chunkTransfer—Valore booleano che indica se il trasferimento in blocchi è supportato.

"x-ms-capabilities": {
  "chunkTransfer": true
}

x-ms-trigger

Indica se l'operazione corrente è un trigger che produce un singolo evento. L'assenza di questo campo significa che si tratta di un'operazione action.

Si applica a: Operazioni

• single—Risposta di tipo oggetto
• batch—Risposta di tipo matrice

"x-ms-trigger": "batch"

x-ms-trigger-hint

Descrizione di come attivare un evento per un'operazione di trigger.

Si applica a: Operazioni

"x-ms-trigger-hint": "To see it work, add a task in Outlook."

x-ms-notification-content

Contiene una definizione dello schema di una richiesta di notifica del webhook. Si tratta dello schema per un payload del webhook inviato da servizi esterni all'URL di notifica.

Si applica a: risorse

"x-ms-notification-content": {
      "schema": {
        "$ref": "#/definitions/WebhookPayload"
      }
    },

x-ms-notification-url

Identifica in un valore booleano se è necessario inserire un URL di notifica del webhook in questo parametro/campo per un'operazione di registrazione del webhook.

Si applica a: campi Parametro/input

"x-ms-notification-url": true

x-ms-url-encoding

Identifica se il parametro del percorso corrente deve essere double con codifica URL doppia o single con codifica URL singola. L'assenza di questo campo indica la codifica single.

Si applica a: parametri di percorso

"x-ms-url-encoding": "double"

Usare i valori dinamici

I valori dinamici sono un elenco di opzioni che consentono all'utente di selezionare i parametri di input per un'operazione. 

Si applica a: Parametri 

Come usare i valori dinamici

Nota

Una stringa di percorso è un puntatore JSON che non contiene la barra in avanti. Quindi, questo è un puntatore JSON: /property/childProperty e questa è una stringa di percorso: property/childProperty.

La definizione dei valori può essere eseguita in due modi:

1. Utilizzare x-ms-dynamic-values

   Nome	Necessari	Descrizione
   operationId	Sì	L'operazione che restituisce i valori.
   parameters	Sì	Oggetto che fornisce i parametri di input necessari per richiamare un'operazione dynamic-values.
   value-collection	No	Stringa di percorso che valuta una matrice di oggetti nel payload della risposta. Se value-collection non è specificato, la risposta viene valutata come una matrice.
   value-title	No	Stringa di percorso dell'oggetto all'interno di value-collection che fa riferimento alla descrizione del valore.
   value-path	No	Stringa di percorso dell'oggetto all'interno di value-collection che fa riferimento al valore del parametro.

   "x-ms-dynamic-values": {
       "operationId": "PopulateDropdown",
       "value-path": "name",
       "value-title": "properties/displayName",
       "value-collection": "value",
       "parameters": {
           "staticParameter": "<value>",
           "dynamicParameter": {
               "parameter": "<name of the parameter to be referenced>"
           }
       }
   }  
   

   Nota

   È possibile avere riferimenti a parametri ambigui quando si utilizzano valori dinamici. Ad esempio, nella seguente definizione di un'operazione, i valori dinamici fanno riferimento al campo id che è ambiguo nella definizione poiché non è chiaro se fa riferimento al parametro id o alla proprietà requestBody/id.

   {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicValuesWithAmbiguousReferences",
       "parameters": [{
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
       }, {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "id": {
                       "description": "The request Id",
                       "type": "string"
                   },
                   "model": {
                       "description": "The model",
                       "type": "string",
                       "x-ms-dynamic-values": {
                           "operationId": "GetSupportedModels",
                           "value-path": "name",
                           "value-title": "properties/displayName",
                           "value-collection": "value",
                           "parameters": {
                               "requestId": {
                                   "parameter": "id"
                               }
                           }
                       }
                   }
               }
           }
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "type": "object"
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

2. x-ms-dynamic-list

   Non esiste un modo per fare riferimento ai parametri in modo inequivocabile. Questa funzione potrebbe essere fornita in futuro. Se si vuole che l'operazione sfrutti i nuovi aggiornamenti, aggiungere la nuova estensione x-ms-dynamic-list insieme a x-ms-dynamic-values. Inoltre, se l'estensione dinamica fa riferimento a proprietà all'interno di parametri, è necessario aggiungere la nuova estensione x-ms-dynamic-list insieme a x-ms-dynamic-values. I riferimenti ai parametri che puntano a proprietà devono essere espressi come stringhe di percorso.

   • parameters: questa proprietà è un oggetto in cui ogni proprietà di input dell'operazione dinamica chiamata viene definita con un campo valore statico o un riferimento dinamico alla proprietà dell'operazione di origine. Entrambe queste opzioni sono definite di seguito.

   • value: il valore letterale da usare per il parametro di input. Di seguito, ad esempio, il parametro di input dell'operazione GetDynamicList denominata versione viene definito usando il valore statico 2.0.

     {
         "operationId": "GetDynamicList",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference: il percorso completo di riferimento al parametro, che inizia con il nome del parametro seguito dalla stringa di percorso della proprietà a cui fare riferimento. Ad esempio, la proprietà di input dell'operazione GetDynamicList denominata property1, che è sotto il parametro destinationInputParam1 è definita come riferimento dinamico a una proprietà denominata property1 sotto il parametro sourceInputParam1 dell'operazione di origine.

     {
         "operationId": "GetDynamicList",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     Nota

     Se si vuole fare riferimento a una proprietà contrassegnata come interna con un valore predefinito, è necessario usare il valore predefinito come valore statico nella definizione invece di parameterReference. Il valore predefinito dell'elenco non viene usato se è definito con parameterReference.

     Nome	Obbligatorio	Descrizione
     operationId	Sì	L'operazione che restituisce l'elenco.
     parameters	Sì	Oggetto che fornisce i parametri di input necessari per richiamare un'operazione di elenco dinamico.
     itemsPath	No	Stringa di percorso che valuta una matrice di oggetti nel payload della risposta. Se non si specifica  itemsPath , la risposta viene valutata come una matrice.
     itemTitlePath	No	Una stringa di percorso dell'oggetto all'interno di  itemsPath  che fa riferimento alla descrizione del valore.
     itemValuePath	No	Una stringa di percorso nell'oggetto all'interno di  itemsPath  che fa riferimento al valore dell'elemento.

     Con x-ms-dynamic-list usare i riferimenti ai parametri con la stringa di percorso della proprietà a cui viene fatto riferimento. Utilizza questi riferimenti ai parametri sia per la chiave che per il valore del riferimento ai parametri dell'operazione dinamica.

     {
       "summary": "Tests dynamic values with ambiguous references",
       "description": "Tests dynamic values with ambiguous references.",
       "operationId": "TestDynamicListWithAmbiguousReferences",
       "parameters": [
         {
           "name": "id",
           "in": "path",
           "description": "The request id.",
           "required": true
         },
         {
           "name": "requestBody",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
             "description": "Input body to execute the request",
             "type": "object",
             "properties": {
               "id": {
                 "description": "The request id",
                 "type": "string"
               },
               "model": {
                 "description": "The model",
                 "type": "string",
                 "x-ms-dynamic-values": {
                   "operationId": "GetSupportedModels",
                   "value-path": "name",
                   "value-title": "properties/displayName",
                   "value-collection": "cardTypes",
                   "parameters": {
                     "requestId": {
                       "parameter": "id"
                     }
                   }
                 },
                 "x-ms-dynamic-list": {
                   "operationId": "GetSupportedModels",
                   "itemsPath": "cardTypes",
                   "itemValuePath": "name",
                   "itemTitlePath": "properties/displayName",
                   "parameters": {
                     "requestId": {
                       "parameterReference": "requestBody/id"
                     }
                   }
                 }
               }
             }
           }
         }
       ],
       "responses": {
         "200": {
           "description": "OK",
           "schema": {
             "type": "object"
           }
         },
         "default": {
           "description": "Operation Failed."
         }
       }
     } 
     

Usare lo schema dinamico

Lo schema dinamico indica che lo schema per il parametro o la risposta corrente è dinamico. Questo oggetto richiama un'operazione che viene definita dal valore in questo campo, individua in modo dinamico lo schema e visualizza l'interfaccia utente appropriata per la raccolta dell'input utente o visualizza i campi disponibili.

Si applica a: Parametri, Risposte

Questa immagine illustra come cambia il modulo di input, in base all'elemento selezionato dall'utente dall'elenco:

Questa immagine illustra invece come cambiano gli output, in base all'elemento selezionato dall'utente dall'elenco a discesa. In questa versione, l'utente seleziona Auto:

In questa versione, l'utente seleziona Cibo:

Come usare lo schema dinamico

Nota

Una stringa di percorso è un puntatore JSON che non contiene la barra in avanti. Quindi, questo è un puntatore JSON: /property/childProperty e questa è una stringa di percorso: property/childProperty.

La definizione dello schema può essere eseguita in due modi:

1. x-ms-dynamic-schema:

   Nome	Necessari	Descrizione
   operationId	Sì	L'operazione che restituisce lo schema.
   parameters	Sì	Oggetto che fornisce i parametri di input necessari per richiamare un'operazione dynamic-schema.
   value-path	No	Stringa di percorso che fa riferimento alla proprietà che contiene lo schema. Se non specificato, la risposta si presuppone contenere lo schema nelle proprietà dell'oggetto radice. Se specificato, la risposta corretta deve contenere la proprietà. Per uno schema vuoto o indefinito questo valore deve essere Null.

     {
     "name": "dynamicListSchema",
     "in": "body",
     "description": "Dynamic schema for items in the selected list",
     "schema": {
         "type": "object",
         "x-ms-dynamic-schema": {
             "operationId": "GetListSchema",
             "parameters": {
                 "listID": {
                     "parameter": "listID-dynamic"
                 }
             },
             "value-path": "items"
         }
       }
     }
   

   Nota

   Potrebbero esserci riferimenti ambigui nei parametri. Nella definizione seguente di un'operazione, ad esempio, lo schema dinamico fa riferimento a un campo denominato query, che non può essere compreso in modo deterministico dalla definizione, ovvero se fa riferimento all'oggetto del parametro query o alla proprietà della stringa query/query.

   {
   
       "summary": "Tests dynamic schema with ambiguous references",
       "description": "Tests dynamic schema with ambiguous references.",
       "operationId": "TestDynamicSchemaWithAmbiguousReferences",
       "parameters": [{
           "name": "query",
           "in": "body",
           "description": "query text.",
           "required": true,
           "schema": {
               "description": "Input body to execute the request",
               "type": "object",
               "properties": {
                   "query": {
                       "description": "Query Text",
                       "type": "string"
                   }
               }
           },
           "x-ms-summary": "query text"
       }],
       "responses": {
           "200": {
               "description": "OK",
               "schema": {
                   "x-ms-dynamic-schema": {
                       "operationId": "GetDynamicSchema",
                       "parameters": {
                           "query": {
                               "parameter": "query"
                           }
                       },
                       "value-path": "schema/valuePath"
                   }
               }
           },
           "default": {
               "description": "Operation Failed."
           }
       }
   }
   

   Esempi di connettori open source

   Connettore	Scenario	Collegamento
   Creazione di ticket	Ottieni schema per i dettagli dell'evento selezionato	Creazione di ticket

2. x-ms-dynamic-properties:

   Non esiste un modo per fare riferimento ai parametri in modo inequivocabile. Questa funzione potrebbe essere fornita in futuro. Se si vuole che l'operazione sfrutti i nuovi aggiornamenti, aggiungere la nuova estensione x-ms-dynamic-properties insieme a x-ms-dynamic-schema. Inoltre, se l'estensione dinamica fa riferimento a proprietà all'interno di parametri, è necessario aggiungere la nuova estensione x-ms-dynamic-properties insieme a x-ms-dynamic-schema. I riferimenti ai parametri che puntano a proprietà devono essere espressi come stringhe di percorso.

   • parameters: questa proprietà è un oggetto in cui ogni proprietà di input dell'operazione dinamica chiamata viene definita con un campo valore statico o un riferimento dinamico alla proprietà dell'operazione di origine. Entrambe queste opzioni sono definite di seguito.

   • value: il valore letterale da usare per il parametro di input. Di seguito, ad esempio, il parametro di input dell'operazione GetDynamicSchema denominata version viene definito con il valore statico 2.0.

     {
         "operationId": "GetDynamicSchema",
         "parameters": {
           "version": {
             "value": "2.0"
           }
         }
     }
     

   • parameterReference: il percorso completo di riferimento al parametro, che inizia con il nome del parametro seguito dalla stringa di percorso della proprietà a cui fare riferimento. Ad esempio, la proprietà di input dell'operazione GetDynamicSchema denominata property1, che è sotto il parametro destinationInputParam1 è definita come riferimento dinamico a una proprietà denominata property1 sotto il parametro sourceInputParam1 dell'operazione di origine.

     {
         "operationId": "GetDynamicSchema",
           "parameters": {
               "destinationInputParam1/property1": {
                 "parameterReference": "sourceInputParam1/property1"
         }
       }
     }
     

     Nota

     Se si vuole fare riferimento a una proprietà contrassegnata come interna con un valore predefinito, è necessario usare il valore predefinito come valore statico nella definizione invece di parameterReference. Il valore predefinito dello schema non viene usato se è definito con parameterReference.

     Nome	Obbligatorio	Descrizione
     operationId	Sì	L'operazione che restituisce lo schema.
     parameters	Sì	Oggetto che fornisce i parametri di input necessari per richiamare un'operazione dynamic-schema.
     itemValuePath	No	Stringa di percorso che fa riferimento alla proprietà che contiene lo schema. Se non specificato, la risposta si presuppone contenere lo schema nell'oggetto radice. Se specificato, la risposta corretta deve contenere la proprietà. Per uno schema vuoto o indefinito questo valore deve essere Null.

     Con x-ms-dynamic-properties i riferimenti ai parametri possono essere usati con la stringa di percorso della proprietà a cui fare riferimento sia per la chiave che per il valore del riferimento al parametro dell'operazione dinamica.

         {
         "summary": "Tests dynamic schema with ambiguous references",
         "description": "Tests dynamic schema with ambiguous references.",
         "operationId": "TestDynamicSchemaWithAmbiguousReferences",
         "parameters": [{
             "name": "query",
             "in": "body",
             "description": "query text.",
             "required": true,
             "schema": {
                 "description": "Input body to execute the request",
                 "type": "object",
                 "properties": {
                     "query": {
                         "description": "Query Text",
                         "type": "string"
                     }
                 }
             },
             "x-ms-summary": "query text"
         }],
         "responses": {
             "200": {
                 "description": "OK",
                 "schema": {
                     "x-ms-dynamic-schema": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": "2.0",
                             "query": {
                                 "parameter": "query"
                             }
                         },
                         "value-path": "schema/valuePath"
                     },
                     "x-ms-dynamic-properties": {
                         "operationId": "GetDynamicSchema",
                         "parameters": {
                             "version": {
                                 "value": "2.0"
                             },
                             "query/query": {
                                 "parameterReference": "query/query"
                             }
                         },
                         "itemValuePath": "schema/valuePath"
                     }
                 }
             },
             "default": {
                 "description": "Operation Failed."
             }
           }
         }
     

Passaggio successivo

Creare un connettore personalizzato da una definizione OpenAPI

Vedi anche

Panoramica dei connettori personalizzati

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.