Aprender as melhores práticas para campos de cadeia (de carateres)

  • Artigo

O artigo seguinte contém orientações gerais para campos de cadeia num conector para o Power Automate, Power Apps e Azure Logic Apps.

Informações de conector

Cada conector deve ter um título, que é o nome do conector e uma descrição, que descreve o conector em geral. Estas informações devem ser especificadas nos campos título e descrição na secção info na definição OpenAPI (no ficheiro apiDefinition.swagger.json).

No mínimo, devem ser seguidas as seguintes diretrizes para títulos e descrições do conector:

  • O título do conector pode ter um máximo de 30 carateres.
  • O título e a descrição do conector não podem incluir a palavra API.
  • O título e a descrição do conector não podem fazer referência a um produto do Power Platform ou a um produto do qual não seja o proprietário das APIs de back-end.

Uma norma mais elevada de diretrizes para os campos de título e descrição aplicadas a conectores certificados podem ser encontradas aqui e devem ser utilizadas como melhores práticas.

Operações

Cada caminho e verbo na definição de OpenAPI corresponde a uma operação. Descrever corretamente a operação com cada uma das cadeias de carateres/etiquetas abaixo ajuda o utilizador final a utilizá-la corretamente. Alguns dos campos de cadeia de uma operação são:

  • resumo: será apresentado como o nome da operação.

    • Incidente: frase
    • Notas:
      • Não deve haver uma barra ('/') no nome.
      • Não deve exceder 80 carateres.
      • Não deve terminar com um caráter não alfanumérico, incluindo pontuação ou espaço.

  • description: aparecerá como a descrição da operação ao selecionar o botão de informação Captura de ecrã que mostra o botão de informação., como mostrado na imagem que se segue.

    • Caso: frase.
    • Notas: mantenha pequeno para caber na caixa de texto. Não é necessário nenhum ponto final se houver uma única palavra.

  • operationId: este é o ID exclusivo associado à operação.

    • Caso: Sem espaços (sem espaços, nem pontuação).
    • Notas: destina-se a transmitir o significado da operação, como, por exemplo, GetContacts ou CreateContact.

    A imagem que se segue mostra como os campos summary—Enviar um e-mail e description—Esta operação envia uma mensagem de e-mail irão aparecer enquanto está a criar um fluxo de trabalho.

    Captura de ecrã que mostra como os campos de resumo e descrição aparecerão.

Acionadores vs. ações

Um acionador inicia um fluxo de trabalho ou processo. Por exemplo, "Iniciar um fluxo de trabalho todas as segundas-feiras às 3:00", "Quando um objeto é criado", etc.

Os campos Resumo do disparo e descrição devem ser legíveis e ter significado semântico. Normalmente, o resumo do acionador está no formato: "Quando um __________________".

Exemplo:

Acionar Resumo
Criar Quando uma tarefa é criada
Actualizar Quando uma tarefa é atualizada
Eliminada Quando uma tarefa é eliminada

Normalmente, descrição, está no formato: "Esta operação é acionada quando _______________"

Exemplo:

  • Esta operação é acionada quando uma nova tarefa é adicionada.

Uma ação é uma tarefa a concluir no seu fluxo de trabalho, como, por exemplo, "Enviar um e-mail", "Atualizar uma linha", "Enviar uma notificação", etc. Seguem-se alguns exemplos de resumo de ações:

Ação Resumo
Criar Criar nova tarefa
Lida Obter Tarefa por ID
Actualizar Atualizar objeto
Eliminada Eliminar objeto
Lista Listar todos os objetos

Parâmetros

Cada operação (seja um acionador ou uma ação) tem parâmetros que o utilizador fornece como entrada. Alguns dos campos de cadeia importantes de um parâmetro são:

  • x-ms-resumo: será apresentado como o nome do parâmetro.

    • Incidente: título
    • Notas: tem um limite de 80 carateres

  • descrição: isto será mostrado como a descrição do parâmetro na caixa de entrada.

    • Incidente: frase
    • Notas: mantenha pequeno para caber na caixa de texto. Não é necessário nenhum ponto final se houver uma única palavra.

    Na imagem abaixo, o parâmetro realçado tem "Subject" (Assunto) como o valor do campo x-ms-summary e tem "Specify the subject of the mail" (Especificar o assunto da mensagem) como o valor do campo description.

    Captura de ecrã que mostra os valores dos parâmetro x-ms-summary e description na interface.

Response

Cada operação tem uma resposta que pode ser utilizada posteriormente no fluxo de trabalho como entrada de uma operação subsequente. O esquema de resultados é composto de várias propriedades. Alguns dos campos de cadeia importantes para cada propriedade são:

  • x-ms-resumo: será apresentado como o nome da propriedade de resultado.

    • Incidente: título
    • Notas: utilize um nome curto.

  • descrição: será apresentado como a descrição para a propriedade de resultado.

    • Incidente: frase
    • Notas: deve ser breve e conciso, com um ponto no final.

    Na imagem mostrada abaixo, o esquema de resultados da operação "Acionar manualmente um fluxo" é apresentado quando tenta adicionar conteúdo dinâmico a uma das operações subsequentes no fluxo de trabalho. Aqui, "User email" (E-mail do utilizador) é o campo x-ms-summary e o texto abaixo é o campo descrição de uma propriedade na resposta da operação "Acionar manualmente um fluxo".

resposta

Algumas notas importantes que deve considerar em geral relativamente aos campos summary/x-ms-summary e description são:

  • Os textos de resumo e de descrição não deverão ser os mesmos.
  • O campo description deve ser utilizado para fornecer ao utilizador informações adicionais, tais como o formato de saída ou o objeto com o qual a propriedade está relacionada. Por exemplo: resumo : ID, descrição: ID do utilizador.
  • Para um objeto com valores aninhados, o campo x-ms-summary do nome principal será acrescentado ao subordinado.

x-ms-visibility

Determina a prioridade da visibilidade da entidade. Se não especificar nenhuma visibilidade, consideramos essa visibilidade como "normal". Os valores possíveis são "important" (importante), "advanced" (avançado) ou "internal" (interno). As entidades marcadas como "internas" não são mostradas na interface de utilizador.

Aplica-se:

  • Operações
  • Parâmetros
  • Propriedades da resposta

Exemplo:

Na IU, as entidades marcadas como "importantes" são apresentadas em primeiro lugar, as marcadas como "avançadas" estão ocultas num botão de ativar/desativar (realçado) e as marcadas como "internas" não são apresentadas. A imagem que se segue é um exemplo de parâmetros marcados como "importantes" por predefinição. Também mostra parâmetros marcados como "avançados" depois de selecionar o botão Mostrar opções avançadas.

Captura de ecrã que mostra uma lista pendente para as opções avançadas.

Captura de ecrã que mostra as opções avançadas ocultas expandidas.

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.