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

Este artigo fornece orientação geral para campos de string dentro de um conector para Microsoft Power Automate, Microsoft Power Apps, Microsoft Copilot Studio e Azure Logic Apps.

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 seu conector vai no campo título . Uma descrição do seu conector vai no campo _description_field. Ambos os campos aparecem na seção info 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á um máximo de 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 a um produto da Power Platform ou a um produto do qual você não possui as APIs de back-end.

Para obter mais informações sobre as diretrizes do conector certificado, acesse o artigo sobre envio de certificação. Consulte-o para obter as melhores práticas.

Operações

Cada caminho e verbo na definição OpenAPI corresponde a uma operação. Descrever corretamente a operação com cada uma das seguintes strings/tags listadas ajuda o usuário final a utilizá-la corretamente. Aqui estão alguns exemplos de campos de string para uma operação:

• summary aparece 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 aparece 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 é o ID exclusivo associado à operação.

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

  A imagem mostra como os campos resumo—Enviar um e-mail e descrição—Esta operação envia uma mensagem de e-mail aparecem enquanto você cria um fluxo de trabalho.

  

Gatilhos em comparação com ações

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

• Inicie um fluxo de trabalho toda segunda-feira às 3 da manhã
• Quando um objeto é criado

Certifique-se de que os campos de resumo e descrição do gatilho sejam legíveis e tenham significado semântico. O resumo do gatilho geralmente está no formato: _Quando um ___________________.

Exemplo:

Gatilho	Resumo
Criar	Quando uma tarefa é criada
Atualizar	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 a ser concluída dentro do seu fluxo de trabalho, como Enviar um e-mail, Atualizar uma linha e Enviar uma notificação. Aqui estão alguns exemplos de resumo de ações :

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 como o nome do parâmetro.

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

• description aparece como a descrição do parâmetro dentro da 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 uma única palavra.

  Esta imagem mostra que o parâmetro destacado tem Assunto como o valor para o campo x-ms-summary e Especificar o assunto do e-mail 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 de string importantes para cada propriedade são:

• x-ms-summary aparece como o nome da propriedade resultante.

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

• description aparece como a descrição da propriedade result.

  • Ocorrência: frase
  • Observações: Mantenha a descrição curta e concisa, com um ponto final.

  Na imagem, o esquema de resultado da operação Acionar manualmente um fluxo aparece quando você tenta adicionar conteúdo dinâmico em uma das operações subsequentes no fluxo de trabalho. Aqui, E-mail do usuário é o x-ms-summary e o texto abaixo dele é a descrição de uma propriedade na resposta da operação Acionar manualmente um fluxo .

Aqui estão algumas notas 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 ao qual a propriedade está relacionada. Por exemplo: resumo : ID, descrição: ID do usuário.
• Para um objeto com valores aninhados, o x-ms-summary do nome pai é anexado ao filho.

Prioridade de visibilidade

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

A visibilidade se aplica a:

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

Veja um exemplo:

Na IU, as entidades marcadas como importantes são exibidas primeiro, as coisas marcadas como avançadas são ocultas sob um botão de alternância (destacado) e as coisas marcadas como internas não são exibidas. A imagem mostra um exemplo de parâmetros marcados como importantes sendo exibidos por padrão. Você também pode ver os parâmetros marcados como avançados depois de 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 feedback, acesse Enviar problemas ou obter ajuda com conectores e selecione seu tipo de feedback.