Guía de la cadena de conector

El siguiente tema contiene instrucciones generales para los campos de cadena de un conector para Power Automate, Power Apps y Logic Apps.

Información del conector

Cada conector debe tener un título, que es el nombre del conector, y una descripción, que describe el conector en general. Esta información debe especificarse en los campos title y description de la sección info de la definición de OpenAPI (en el archivo apiDefinition.swagger.json).

Se deben seguir las siguientes directrices como mínimo para los títulos y las descripciones de los conectores:

• El título del conector puede tener 30 caracteres como máximo.
• El título y la descripción del conector no pueden incluir la palabra API.
• El título y la descripción del conector no pueden hacer referencia a un producto de Power Platform ni a un producto cuyas API de back-end no posea.

Puede encontrar un nivel más elevado de instrucciones de los campos de título y descripción de los conectores certificados aquí y se debería usar este como procedimiento recomendado.

Operaciones

Cada ruta de acceso y verbo de la definición de OpenAPI corresponde a una operación. Describir correctamente la operación con cada una de las siguientes cadenas/etiquetas ayuda al cliente final a usarla correctamente. Algunos de los campos de cadena para una operación son:

• summary: aparecerá como el nombre de la operación.

  • Capitalización: Oración
  • Notas:
    • No debe haber una barra ('/') en el nombre.
    • No debe superar los 80 caracteres.
    • No debe acabar con un carácter no alfanumérico, lo que incluye la puntuación o los espacios.

• description: se mostrará como la descripción de la operación al seleccionar el botón de información (como se muestra en la imagen siguiente).

  • Capitalización: Oración
  • Notas: Manténgase corto para que quepa en el cuadro de texto. No se requiere punto en caso de una sola palabra.

• operationId: este es el identificador único asociado a la operación.

  • Capitalización: Camel
  • Notas: Sirve para comunicar el significado de la operación, como GetContacts o CreateContact.

  La imagen siguiente muestra cómo los campos summary (Enviar un correo electrónico) y description (Esta operación envía un correo electrónico) aparecerán en la interfaz de usuario durante la creación de un flujo de trabajo.

  

Desencadenadores frente a acciones

Un desencadenador inicia un flujo de trabajo o proceso. Por ejemplo, "Iniciar un flujo de trabajo todos los lunes a las 3 a.m.", "Cuando se crea un objeto", etc.

Los campos de resumen y descripción del desencadenador deben ser legibles por el hombre y tener un significado semántico. El desencadenador summary generalmente está en el formato: "Cuando __________________".

Ejemplo:

El desencadenador description generalmente está en el formato: "Esta operación se desencadena cuando _______________"

Ejemplo:

• Esta operación se desencadena cuando se agrega una nueva tarea.

Una acción es una tarea que completar en el flujo de trabajo, como "Enviar un correo electrónico", "Actualizar una fila" o "Enviar una notificación", etc. Tiene algunos ejemplos de la acción summary a continuación:

Parámetros

Cada operación (ya sea un desencadenador o una acción) tiene parámetros que el usuario proporciona como entrada. Algunos de los campos de cadena importantes para un parámetro son:

• x-ms-summary: aparecerá como el nombre del parámetro.

  • Capitalización: Título
  • Nota: Tiene un límite de 80 caracteres.

• description: aparecerá como la descripción del parámetro dentro del cuadro de entrada.

  • Capitalización: Oración
  • Nota: Manténgase corto para que quepa en el cuadro de texto. No se requiere punto en caso de una sola palabra.

  En la imagen que se muestra a continuación, el parámetro resaltado tiene "Subject" como valor del campo x-ms-summary y "Especifique el asunto del correo" como el de description.

  

Response

Cada operación tiene una respuesta que se puede usar más adelante en el flujo de trabajo como entrada para una operación posterior. El esquema resultante está compuesto por múltiples propiedades. Algunos de los campos de cadena importantes para cada propiedad son:

• x-ms-summary: aparecerá como el nombre de la propiedad de resultado.

  • Capitalización: Título
  • Nota: Use un nombre corto.

• description: aparecerá como la descripción de la propiedad del resultado.

  • Capitalización: Oración
  • Nota: Debe ser breve y conciso, con un punto al final.

  En la imagen que se muestra a continuación, el esquema de resultados de la operación "Activar manualmente un flujo" aparece cuando intenta agregar contenido dinámico en una de las operaciones posteriores en el flujo de trabajo. En este caso, "Correo electrónico del usuario" es x-ms-summary y el texto de debajo, es el campo description de una propiedad de la respuesta de la operación "Desencadenar un flujo manualmente".

Ejemplos de notas importantes que deben considerarse como norma general para los campos summary/x-ms-summary y description:

• El resumen y el texto descriptivo no deben ser iguales.
• La descripción debe usarse para proporcionar información adicional al usuario, como el formato de salida o el objeto relacionado con la propiedad. Por ejemplo: summary : ID, description: ID de usuario.
• En el caso de un objeto con valores anidados, se anexará x-ms-summary del nombre principal al secundario.

x-ms-visibility

Determina la prioridad de visibilidad de la entidad. Si no se especifica ninguna visibilidad, se considerará "normal". Los valores posibles son "important", "advanced" o "internal". Las entidades que se marcan como "internas" no aparecen en la interfaz de usuario.

Se aplica a:

• Operaciones
• Parámetros
• Propiedades de respuesta

Ejemplo: en la interfaz de usuario, las entidades marcadas como "important" normalmente aparecen en primer lugar, las cosas marcadas como "advanced" se ocultan en un botón de alternancia (resaltado) y las marcadas como "internal" no aparecen. Por ejemplo, como se muestra en la imagen a continuación, los parámetros marcados como "importantes" se muestran por defecto y los parámetros marcados como "avanzados" se muestran después de hacer clic en el botón "Mostrar opciones avanzadas".