Creare un connettore personalizzato con un'estensione OpenAPI

Un modo per creare connettori personalizzati per Microsoft Copilot Studio, App per la logica di Azure, Microsoft Power Automate o Microsoft Power Apps consiste nel fornire un file di definizione OpenAPI. Un file di definizione OpenAPI è un documento indipendente dal linguaggio e leggibile dalla macchina che descrive le operazioni e i parametri della tua API. Oltre alla funzionalità predefinita di OpenAPI, le seguenti estensioni di OpenAPI possono anche essere incluse quando si creano connettori personalizzati per Logic Apps 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: utilizzare 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: utilizzare la maiuscola a inizio frase per x-ms-summary.
Esempio: ID calendario, Oggetto, Descrizione evento

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

descrizione

Fornisce 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: utilizzare 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.

Possibili valori: important, advanced e internal
Si applica a: Operazioni, parametri, schemi

• L'utente vede sempre prima le operazioni e i parametri su important.
• L'utente visualizza advanced le operazioni e i parametri solo quando usano un menu aggiuntivo.
• L'utente non visualizza internal operazioni e parametri.

Esempio: i menu Visualizza altro e Mostra opzioni avanzate nascondono advanced operazioni e parametri.

"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

Usare 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

Usare questa proprietà per simulare l'attivazione di un trigger in modo da poter testare un flusso dipendente dal trigger.

Si applica a: Operazioni

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

x-ms-capabilities

Quando si usa questa proprietà a livello di connettore, offre una panoramica delle funzionalità offerte dal connettore, incluse operazioni specifiche.

Si applica a: Connettori

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

Quando si usa questa proprietà a livello di operazione, identifica che l'operazione supporta il caricamento in blocchi e le dimensioni statiche dei blocchi, che l'utente può fornire.

Si applica a: Operazioni

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

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

x-ms-trigger

Indica se l'operazione corrente è un trigger che produce un singolo evento. Se questo campo è assente, l'operazione è un action.

Si applica a: Operazioni

• single: oggetto risposta
• batch—risposta di tipo array

"x-ms-trigger": "batch"

x-ms-trigger-hint

Descrive come scatenare un evento per un'operazione di innesco.

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. Questo schema definisce il payload del webhook che i servizi esterni pubblicano nell'URL di notifica.

Si applica a: risorse

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

x-ms-notification-url

Usare un valore booleano per specificare se includere un URL di notifica webhook in questo parametro o campo per un'operazione di registrazione webhook.

Si applica a: Parametri e campi di input

"x-ms-notification-url": true

x-ms-url-encoding

Specificare se il parametro path corrente deve usare la doppia codifica URL (double) o la codifica URL singola (single). Se questo campo non è presente, per impostazione predefinita viene impostata la single codifica.

Si applica a: parametri di percorso

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

x-ms-dynamic-values

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

Valori dinamici per mostrare gli elenchi.

Come usare i valori dinamici

È possibile definire valori dinamici in due modi:

• Utilizzare x-ms-dynamic-values

  Nome	Richiesto	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>"
          }
      }
  }  
  

{
    "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."
        }
    }
}

• Utilizzare x-ms-dynamic-list

  Non è possibile fare riferimento senza ambiguità ai parametri. 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 alle proprietà all'interno dei 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 si definisce ogni proprietà di input dell'operazione dinamica chiamata con un campo valore statico o un riferimento dinamico alla proprietà dell'operazione di origine. Entrambe queste opzioni sono definite nella sezione seguente.

  • value: 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: percorso di riferimento del parametro completo, a partire dal 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"
        }
      }
    }
    

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."
    }
  }
} 

x-ms-dynamic-schema

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

L'immagine seguente mostra come cambia il modulo di input, in base all'elemento selezionato dall'utente nell'elenco:

L'immagine seguente mostra come cambiano gli output, in base all'elemento selezionato dall'utente nell'elenco a discesa. In questa versione, l'utente seleziona Auto:

In questa versione, l'utente seleziona Cibo:

Come usare lo schema dinamico

È possibile definire lo schema dinamico in due modi:

• x-ms-dynamic-schema:

  Nome	Richiesto	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 si specifica questa proprietà, si presuppone che la risposta contenga lo schema nelle proprietà dell'oggetto radice. Se specificato, la risposta di successo 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"
        }
      }
    }
  

{

    "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

• 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 alle proprietà all'interno dei 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 si definisce ogni proprietà di input dell'operazione dinamica chiamata con un campo valore statico o un riferimento dinamico alla proprietà dell'operazione di origine. Entrambe queste opzioni sono definite nella sezione seguente.

  • value: 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

  Per fare riferimento a qualsiasi proprietà contrassegnata come interna con un valore predefinito, usare il valore predefinito come valore statico nella definizione, anziché parameterReference. Il valore predefinito dello schema non viene usato se è definito con parameterReference.

  Nome	Richiesto	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.

  x-ms-dynamic-propertiesUsando , è possibile usare i riferimenti ai parametri 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

Informazioni correlate

Panoramica dei connettori personalizzati

Fornire 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.