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

Este artigo fornece orientações gerais para campos da cadeia de caracteres com um conector para o Microsoft Power Automate, o Microsoft Power Apps, o Microsoft Copilot Studio e os Aplicativos Lógicos do Azure.

Informações do conector

É importante que você forneça informações básicas sobre seu conector. Para começar, siga as diretrizes básicas descritas nesta seção. O nome do conector vai no campo de título. A descrição do seu conector vai no description_field. Ambos os campos aparecem na seção informações na definição OpenAPI (o arquivo apiDefinition.swagger.json).

Aqui estão alguns requisitos mínimos a serem seguidos para títulos e descrições de conectores:

• Há, no máximo, 30 caracteres no título do conector.
• 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 ao Microsoft Copilot Studio ou a qualquer outro produto do Microsoft Power Platform.
• O título e a descrição do conector não podem se referir a um produto do qual você não possui as APIs de back-end.

Para obter mais informações sobre diretrizes de conectores certificados, vá para o artigo de envio de certificação. Consulte-o para obter as práticas recomendadas.

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 de caracteres/marcas listadas a seguir ajuda o usuário final a usá-la corretamente. Aqui estão alguns exemplos de campos da cadeia de caracteres de uma operação:

• summary: mostra 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 aparece como a descrição da operação ao selecionar o botão 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: transmite o significado da operação, como GetContacts ou CreateContact.

  A imagem mostra como os campos summary—Enviar um email e description—Esta operação envia uma mensagem de email aparecem ao criar um fluxo de trabalho.

  

Gatilhos em comparação com ações

Um gatilho inicia um fluxo de trabalho ou processo. Alguns exemplos são:

• Iniciar um fluxo de trabalho todas as segundas-feiras às 3h da manhã
• Quando um objeto é criado

Certifique-se de que os campos summary e description do seu gatilho estejam legíveis e tenham significado semântico. O summary do gatilho geralmente está no formato: Quando uma __________________.

Exemplo:

Gatilho	Resumo
Criar	Quando uma tarefa é criada
Atualizar	Quando uma tarefa é atualizada
Excluído(a)	Quando uma tarefa é excluída

A description 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 e Enviar uma notificação. Aqui estão alguns exemplos da ação summary:

Para	Resumo
Criar	Criar tarefa
Lidas	Obter tarefa por ID
Atualizar	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: aparece com o nome do parâmetro.

  • Ocorrência: título
  • Notas: Este campo de cadeia de caracteres tem um limite de 80 caracteres

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

  • Ocorrência: frase
  • Observações: mantenha a descrição curta para caber na caixa de texto. Não é necessário ponto final se houver apenas uma palavra.

  Esta imagem mostra que o parâmetro destacado tem Assunto como o valor do campo x-ms-summary e Especificar o assunto do email como a descrição.

  

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 campos importantes de cadeia de caracteres para cada propriedade são:

• x-ms-summary: aparece como o nome da propriedade do resultado.

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

• description: aparece como a descrição da propriedade do resultado.

  • Ocorrência: frase
  • Observações: mantém a descrição 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 à descrição de uma propriedade na resposta da operação de Disparar manualmente um fluxo.

Aqui estão algumas observações importantes a serem consideradas para os campos summary/x-ms-summary e description:

• O texto de resumo e descrição não deve ser o mesmo.
• A descrição fornece 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 é acrescentado ao filho.

Propriedade de visibilidade

A prioridade de visibilidade da entidade é especificada por x-ms-visibility. Se a visibilidade não for especificada, o valor é considerado visibilidade normal. Os valores possíveis são importante, avançado ou interno. Entidades marcadas como interno não aparecem na interface do usuário.

A visibilidade aplica-se a:

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

Veja um exemplo:

Na interface do usuário, as entidades marcadas como importantes no geral são exibidas primeiro, itens marcados como avançados ficam ocultos por um mecanismo de alternância (em destaque) e itens marcados como internos não são exibidos. A imagem mostra um exemplo de parâmetros marcados como importante sendo mostrados por padrão. Também é possível ver parâmetros marcados como avançados após selecionar o botão Mostrar opções avançadas.

Faça 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.