Introduzione

Per usare le API personalizzate in PowerApps, è necessario specificare una definizione Swagger, ovvero un documento indipendente dalla lingua leggibile al computer in cui siano descritti i parametri e le operazioni dell'API. Oltre alla specifica Swagger integrata, sono disponibili alcune estensioni quando si crea un'API personalizzata per PowerApps.

x-ms-summary

Definisce i nomi visualizzati per le entità il cui campo summary non è specificato nella definizione Swagger.

x-ms-visibility

Indica se l'entità viene visualizzata nella finestra di progettazione di Microsoft Flow. Sono disponibili i seguenti valori:

  • "none" (impostazione predefinita)
  • "advanced"
  • "internal" - nella finestra di progettazione di Microsoft Flow queste operazioni non sono visualizzate

Se un'operazione è contrassegnata come "important", è previsto che il client Microsoft Flow metta in evidenza queste operazioni.

x-ms-trigger

Specifica se questa operazione può essere usata come trigger in un flusso. Le opzioni includono:

  • none (predefinita): l'operazione non può essere usata come trigger.
  • single: questa operazione può essere usata anche come trigger.
  • batched: questa operazione può essere usata come trigger. Questa operazione risponde anche con una matrice di oggetti JSON e il flusso attiva un trigger per ogni elemento della matrice.

x-ms-dynamic-values

Suggerimento per la finestra di progettazione di Microsoft Flow che l'API genera un elenco di valori consentiti dinamicamente per questo parametro. La finestra di progettazione di Microsoft Flow può richiamare un'operazione in base al valore definito in questo campo ed estrarre i valori possibili dal risultato. La finestra di progettazione di Microsoft Flow può quindi visualizzare questi valori come opzioni per l'utente finale.

Il valore è un oggetto che contiene le proprietà seguenti:

  • operationId: stringa che corrisponde a operationId per l'operazione richiamata
  • parameters: oggetto le cui proprietà definiscono i parametri necessari per l'operazione
  • value-collection: stringa di percorso che restituisce una matrice di oggetti nel payload di risposta
  • value-path: stringa di percorso dell'oggetto all'interno di "value-collection" che fa riferimento al valore per il parametro.
  • value-title: stringa di percorso dell'oggetto all'interno di "value-collection" che fa riferimento a una descrizione per il parametro.

Esempio:

"/api/tables/{table}/items": {
  "post": {
    "operationId": "TableData_CreateItem",
    "summary": "Create an object in {Salesforce}",
    "parameters": [
      {
        "name": "table",
        "x-ms-summary": "Object Type",
        "x-ms-dynamic-values": {
          "operationId": "TableMetadata_ListTables",      // operation that needs to be invoked
          "parameters": { },                              // parameters for the above operation, if any
          "value-collection": "values",                   // field that contains the collection
          "value-path": "Name",                           // field that contains the value
          "value-title": "DisplayName"                    // field that contains a display name for the value
      }
      // ...
    ]
    // ...
  }
  // ...
}

In questo esempio, lo Swagger definisce l'operazione TableData_CreateItem che crea un nuovo oggetto in Salesforce.

Salesforce contiene molti oggetti predefiniti. x-ms-dynamic-values qui viene usato a supporto della finestra di progettazione, che deve determinare l'elenco degli oggetti Salesforce predefiniti. Ottiene l'elenco chiamando TableMetadata_ListTables.

x-ms-dynamic-schema

Suggerimento per la progettazione del flusso che indica che lo schema per questo parametro (o la risposta) è di natura dinamica. Può richiamare un'operazione in base al valore del campo e individuare lo schema in modo dinamico. Può quindi visualizzare un'interfaccia utente appropriata per accettare l'input dell'utente o visualizzare i campi disponibili.

Esempio:

{
  "name": "item",
  "in": "body",
  "required": true,
  "x-ms-dynamic-schema": {
    "operationId": "Metadata_GetTableSchema",
    "parameters": {
      "tablename": "{table}"              // the value that the user has selected from the above parameter
    },
    "value-path": "Schema"                // the field that contains the JSON schema
  }
},

Questo è utile in scenari in cui gli input per un'operazione sono dinamici. Nel caso di SQL, ad esempio, lo schema per ogni tabella è diverso. Quando un utente seleziona una determinata tabella, la progettazione del flusso deve comprendere la struttura della tabella in modo che sia possibile visualizzare i nomi delle colonne. In questo contesto, se la definizione Swagger ha x-ms-dynamic-schema, chiama l'operazione corrispondente per recuperare lo schema.

Passaggi successivi

Registrare un'API personalizzata.

Usare un'API Web ASP.NET.

Registrare un'API di Azure Resource Manager.