Partekatu honen bidez:

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

  • Artikulua

El siguiente artículo contiene una guía general para los campos de cadena dentro de un conector para Power Automate, Power Apps y Azure 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 título y descripción, en la sección información 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 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: esto se mostrará como la descripción de la operación al seleccionar el botón de información Captura de pantalla que muestra el botón de información., como se puede ver en la siguiente imagen.

    • 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: Sirve para 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.

    Captura de pantalla que muestra cómo aparecerán los campos de resumen y descripción

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:

Desencadenador Resumen
Crear Cuando se crea una tarea
Actualización Cuando se actualiza una tarea
Eliminada Cuando se elimina una tarea

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:

Acción Resumen
Crear Crear tarea nueva
Leído Obtiene una tarea por id.
Actualización 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
    • Nota: 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
    • Nota: Manténgase corto 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.

    Captura de pantalla que muestra los valores de los parámetros x-ms-summary y descripción en la interfaz.

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

respuesta

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 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.
  • Para 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 "importante" normalmente aparecen en primer lugar, las cosas marcadas como "avanzado" se ocultan en un botón de alternancia (resaltado) y las marcadas como "interno" 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.

Captura de pantalla que muestra una lista desplegable de opciones avanzadas.

Captura de pantalla donde se muestran las opciones avanzadas, ocultas y expandidas.

Proporcionar comentarios

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