Saiba mais sobre as melhores práticas para campos de cadeias de caracteres

O artigo a seguir contém diretrizes gerais para campos de cadeia de caracteres dentro de um conector de Power Automate, Power Apps e Aplicativos Lógicos do Azure.

Informações do conector

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

As seguintes diretrizes devem ser seguidas, no mínimo, para títulos e descrições de conectores:

• O título do conector deve ter, no máximo, 30 caracteres.
• 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 se referir a um produto da Power Platform ou a um produto do qual você não possui as APIs de back-end.

Um padrão mais alto das diretrizes para os campos de título e descrição aplicadas a conectores certificados pode ser encontrado aqui e deve ser usado como melhores práticas.

Operações

Cada caminho e verbo na definição OpenAPI corresponde a uma operação. A descrição adequada da operação com cada uma das cadeias/marcas abaixo ajuda o usuário final a usá-la corretamente. Alguns dos campos de cadeia de caracteres para uma operação são:

• resumo: isso aparecerá como o nome da operação.

  • Ocorrência: frase
  • Observações:
    • Não deve haver barra ('/') no nome.
    • Não deve exceder 80 caracteres.
    • Não deve terminar com um caractere não alfanumérico, incluindo pontuação ou espaço.

• description: isso será exibido como a descrição da operação ao selecionar o botão de informações

  • Ocorrência: frase.
  • Observações: mantenha-a curta para caber na caixa de texto. Sem necessidade de ponto final necessário se houver uma única palavra.

• operationId: esta é a ID exclusiva associada à operação.

  • Ocorrência: CaMel (sem espaços ou pontuação).
  • Observações: tem o objetivo de transmitir o significado da operação, como GetContacts ou CreateContact.

  A imagem a seguir como os campos summary — Enviar um email e description — Esta operação envia uma mensagem de email serão exibidos na interface do usuário ao criar um fluxo de trabalho.

  

Gatilhos em comparação com ações

Um gatilho inicia um fluxo de trabalho ou processo. Por exemplo, "Iniciar um fluxo de trabalho toda segunda-feira às 3:00", "Quando um objeto é criado" etc.

Os campos de resumo e descrição do gatilho devem ser legíveis e ter significado semântico. O resumo do gatilho geralmente está no formato: "Quando uma __________________".

Exemplo:

Gatilho	Resumo
Criar	Quando uma tarefa é criada
Atualização	Quando uma tarefa é atualizada
Excluído(a)	Quando uma tarefa é excluída

A descrição do gatilho geralmente está no formato: "Esta operação é acionada quando _______________"

Exemplo:

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

Uma ação é uma tarefa que deve ser concluída dentro de seu fluxo de trabalho, como "Enviar um email", "Atualizar uma linha", "Enviar uma notificação", entre outras. Alguns exemplos de resumo da ação são fornecidos abaixo:

Ação	Resumo
Criar	Criar tarefa
Lidas	Obter tarefa por ID
Atualização	Atualizar objeto
Excluído(a)	Excluir objeto
Lista	Listar todos os objetos

Parâmetros

Cada operação (seja ela um gatilho ou uma ação) tem parâmetros que o usuário fornece como entrada. Alguns dos campos importantes de cadeia de caracteres para um parâmetro são:

• x-ms-summary: isso será exibido como o nome do parâmetro.

  • Ocorrência: título
  • Observações: tem um limite de 80 caracteres

• description: isso aparecerá como a descrição do parâmetro na caixa de entrada.

  • Ocorrência: frase
  • Observações: mantenha curta para caber na caixa de texto. Nenhum período necessário se houver uma única palavra.

  Na imagem abaixo, o parâmetro destacado tem "Assunto" como o valor para o campo x-ms-summary e "Especificar o assunto do email" como description.

  

Resposta

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

• x-ms-summary: isso será exibido como o nome da propriedade do resultado.

  • Ocorrência: título
  • Observações: use um nome curto.

• descrição: isso será exibido como a descrição da propriedade do resultado.

  • Ocorrência: frase
  • Observações: deve ser curta e concisa, com um ponto no final.

  Na imagem mostrada abaixo, o esquema de resultado da operação "Disparar manualmente um fluxo" é exibido quando você tenta adicionar conteúdo dinâmico em uma das operações subsequentes no fluxo de trabalho. Aqui, "Email de usuário" se refere a x-ms-summary e o texto abaixo se refere ao campo description de uma propriedade na resposta da operação de "Disparar manualmente um fluxo".

Algumas observações importantes que devem ser consideradas em geral para os campos summary/x-ms-summary e description são:

• O texto de resumo e descrição não deve ser o mesmo.
• A descrição deve ser usada para fornecer informações adicionais ao usuário, como o formato de saída ou o objeto relacionado à propriedade. Por exemplo: summary: ID, description: ID do usuário.
• Para um objeto com valores aninhados, o x-ms-summary do nome do pai será acrescentado ao filho.

x-ms-visibility

Determina a prioridade de visibilidade da entidade. Se nenhuma visibilidade for especificada, assumirá visibilidade “normal”. Os valores possíveis são “important”, “advanced” ou “internal”. Entidades marcadas como "interno" não aparecem na interface do usuário.

Aplica-se a:

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

Exemplo:

Na interface do usuário, as entidades marcadas como "important" são exibidas primeiramente. Itens marcados como "advanced" ficam ocultos por um mecanismo de alternância (em destaque) e itens marcados como "internal" não são exibidos. A imagem a seguir é um exemplo de parâmetros marcados como "important" sendo mostrados por padrão. Ela também mostra os parâmetros marcados como "advanced" sendo mostrados após a seleção do botão Mostrar opções avançadas.

Enviar comentários

Agradecemos muito os comentários sobre problemas com nossa plataforma de conectores ou novas ideias de recursos. Para fornecer comentários, acesseEnviar problemas ou obter ajuda com conectores e selecione o tipo de comentário.