Introducción

Para usar API personalizadas en PowerApps, debe proporcionar una definición de Swagger, que es un documento con formato de lectura mecánica e independiente del lenguaje donde se describen las operaciones y los parámetros de la API. Además de la especificación inicial de Swagger, existen algunas extensiones disponibles al crear una API personalizada para PowerApps.

x-ms-summary

Define los nombres para mostrar de las entidades que no tienen el campo summary definido en la definición de Swagger.

x-ms-visibility

Define si la entidad se muestra en el diseñador de Microsoft Flow. Están disponibles los siguientes valores:

  • "none" (valor predeterminado)
  • "advanced"
  • "internal": el diseñador de Microsoft Flow no muestra estas operaciones.

Si una operación está marcada como "important", se espera que el cliente de Microsoft Flow la resalte.

x-ms-trigger

Define si esta operación se puede usar como desencadenador en un flujo. Entre las opciones se incluyen:

  • none (valor predeterminado): la operación no se puede usar como desencadenador.
  • single: esta operación también se puede usar como desencadenador.
  • batched: esta operación se puede usar como desencadenador. Además, esta operación responde con una matriz de objetos JSON, y el flujo activa un desencadenador para cada elemento de la matriz.

x-ms-dynamic-values

Se indica al diseñador de Microsoft Flow que la API proporciona una lista de valores permitidos dinámicamente para este parámetro. El diseñador de Microsoft Flow puede invocar una operación en función del valor definido para este campo y extraer los valores posibles del resultado. Después, el diseñador de Microsoft Flow puede mostrar estos valores como opciones al usuario final.

El valor es un objeto que contiene las siguientes propiedades:

  • operationId: una cadena que coincide con el elemento operationId de la operación que se invoca
  • parameters: un objeto cuyas propiedades definen los parámetros necesarios para la operación
  • value-collection: una cadena de ruta de acceso que se evalúa como una matriz de objetos en la carga útil de respuesta
  • value-path: una cadena de ruta de acceso en el objeto dentro de "value-collection" que hace referencia al valor del parámetro.
  • value-title: una cadena de ruta de acceso en el objeto dentro de "value-collection" que hace referencia a una descripción del valor.

Ejemplo:

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

En este ejemplo, Swagger define la operación TableData_CreateItem que crea un objeto en Salesforce.

Salesforce posee gran cantidad de objetos integrados. x-ms-dynamic-values se usa aquí para ayudar al diseñador a averiguar la lista de objetos integrados de Salesforce. Obtiene la lista mediante una llamada a TableMetadata_ListTables.

x-ms-dynamic-schema

Indica al diseñador de flujo que el esquema para este parámetro (o respuesta) es de naturaleza dinámica. Se puede invocar una operación según el valor definido para este campo y detectar el esquema dinámicamente. Después, puede mostrar una interfaz de usuario adecuada para realizar entradas del usuario o mostrar campos disponibles.

Ejemplo:

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

Esto es útil en escenarios donde las entradas para una operación son dinámicas. Por ejemplo, en el caso de SQL, el esquema para cada tabla es diferente. Cuando un usuario selecciona una tabla determinada, el diseñador de flujo debe comprender su estructura para poder mostrar los nombres de columna. En este contexto, si la definición de Swagger tiene x-ms-dynamic-schema, llama a la operación correspondiente para capturar el esquema.

Pasos siguientes

Registre una API personalizada.

Use una instancia de ASP.NET Web API.

Registre una API de Azure Resource Manager.