Información sobre los procedimientos recomendados para los campos de cadena

El siguiente artículo contiene una guía general para los campos de cadena dentro de un conector para Microsoft Power Automate, Microsoft Power Apps, Microsoft Copilot Studio y Azure Logic Apps.

Información del conector

Es importante que proporcione información básica sobre el conector. Para comenzar, siga las pautas básicas descritas en esta sección. El nombre del conector aparece en el campo título. En el campo Descripción, escriba una descripción del cargo. Ambos campos aparecen en la sección de info de la definición de OpenAPI (el archivo apiDefinition.swagger.json).

Estos son algunos requisitos mínimos que se deben seguir 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 Microsoft Copilot Studio o a cualquier otro producto de Microsoft Power Platform.
• El título y la descripción del conector no pueden hacer referencia a un producto cuyas API de back-end no posea.

Para obtener más información sobre las pautas para conectores certificados, vaya al artículo de envío de certificación. Consúltelo para conocer las prácticas recomendadas.

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 puede superar los 80 caracteres.
    • No debe acabar con un carácter no alfanumérico, lo que incluye la puntuación o los espacios.

• descripción aparece como la descripción de la operación al seleccionar el botón de información. .

  • Mayúsculas: Oración.
  • Notas: Manténgase corto para que quepa en el cuadro de texto. No se requiere punto si hay una sola palabra.

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

  • Mayúsculas: "Camel" (sin espacios ni puntuación).
  • Notas: comunicar el significado de la operación, como GetContacts o CreateContact.

  La imagen siguiente muestra cómo los campos resumen—Enviar un correo electrónico y descripción—esta operación envía un correo electrónico aparecerán durante la creación de un flujo de trabajo.

  

Desencadenadores frente a acciones

Un desencadenador inicia un flujo de trabajo o proceso. Veamos un par de ejemplos:

• Iniciar un flujo de trabajo todos los lunes a las 3 de la madrugada
• Cuando se crea un objeto

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

Ejemplo:

Desencadenador	Resumen
Create	Cuando se crea una tarea
Update	Cuando se actualiza una tarea
Eliminada	Cuando se elimina una tarea

La description del desencadenador suele tener el formato: _Esta operación se inicia 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. Algunos ejemplos de la acción summary a continuación:

Acción	Resumen
Create	Crear tarea nueva
Leído	Obtiene una tarea por id.
Update	Actualizar objeto
Eliminada	Eliminar objeto
Lista	Mostrar todos los objetos

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
  • Notas: Este campo de cadena tiene un límite de 80 caracteres

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

  • Capitalización: Oración
  • Notas: mantenga la descripción corta para que quepa en el cuadro de texto. No se requiere punto si hay 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 de resultado se compone de varias 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 de la descripción no deben ser iguales.
• La descripción proporciona 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.
• Para un objeto con valores anidados, se anexará x-ms-summary del nombre principal al secundario.

Propiedad de visibilidad

La prioridad de visibilidad de la entidad se especifica mediante x-ms-visibility. Si no se especifica ninguna visibilidad, se considerará normal. Los valores posibles son important, advanced o internal. Las entidades que se marcan como internal no aparecen en la interfaz de usuario.

La visibilidad se aplica a:

• Operaciones
• Parámetros
• Propiedades de respuesta

Mostramos ahora un ejemplo:

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. La siguiente imagen es un ejemplo de parámetros marcados como importante que se muestran de forma predeterminada. También muestra los parámetros marcados como avanzado que se muestran después de seleccionar el botón Mostrar opciones avanzadas.

Proporcionar comentarios

Agradecemos enormemente los comentarios sobre problemas con nuestra plataforma de conectores o nuevas ideas de funciones. Para enviar comentarios, vaya a Enviar problemas u obtener ayuda con los conectores y seleccione el tipo de comentario.