Explorar opções de configuração o conector personalizado
Esta unidade continua explicando os fundamentos dos conectores personalizados analisando em profundidade algumas opções de configuração disponíveis.
Nomenclatura do conector e informações gerais
Uma das primeiras decisões que você tomará é o nome do conector. O nome deve ser exclusivo e esclarecer a função do conector para o consumidor. Há um limite de 30 caracteres para esse nome, e é possível elaborar mais no campo Descrição. O campo Cor da tela de fundo do ícone também pode ajudá-lo a identificar visualmente seu conector. Esses campos são importantes porque mostram quando o usuário está selecionando o conector a ser usado e essas dicas visuais ajudam o usuário a trabalhar com mais eficiência. Se você planeja enviar o seu conector para certificação, verifique se os requisitos mais estritos foram revisados na documentação Instruções sobre como enviar seu conector para a documentação da Microsoft.
Ação e nomenclatura de gatilho
Depois que um usuário se restringe ao seu conector, ele escolhe uma ação ou um gatilho para usar no conector. Os campos ID da operação, Resumo e Descrição ajudam a descrever cada ação e gatilho. A ID da operação é usada internamente, deve ser exclusiva e não pode conter espaços. Usar minúsculas concatenadas, como GetInvoice, simplificará a capacidade de ler a ID, caso você esteja examinando o markup da definição. A falta de espaços nos nomes pode ser difícil para os criadores que usam leitores de tela, mas usar o camel case ajudará a tornar suas definições mais acessíveis para eles.
O campo Resumo é importante porque é exibido na lista de ações e gatilhos quando você seleciona aquele a ser usado. Recomendamos que você seja descritivo o suficiente para saber o que a ação ou o gatilho faz. Por exemplo, a descrição da ação GetInvoice poderia ser Obter uma fatura específica por ID. Normalmente, os facilitadores encontrarão a ação pesquisando, portanto, nomes descritivos podem ajudá-los a encontrar a ação correta rapidamente.
A imagem a seguir mostra onde os elementos de resumo e descrição são usados quando você seleciona uma ação ou gatilho.
Depois de selecionar uma ação ou um gatilho, você poderá ver os elementos de resumo e descrição em cada cartão de ação no designer.
Nas imagens anteriores, observe que os padrões de nomenclatura são inconsistentes: alguns nomes têm espaços no resumo e outros não. Você pode corrigir esse erro atualizando os campos no portal ou, se for o proprietário da API, poderá pedir ao desenvolvedor que atualize o que eles fornecem na definição de OpenAPI que você importar. Lembre-se de que, se você fizer alterações manualmente no portal e importar a definição de OpenAPI novamente, ela substituirá suas alterações.
Visibilidade de ação
É possível definir a opção Visibilidade em uma ação para influenciar como ela será mostrada na experiência do criador.
Nenhuma: essa opção é o padrão. A ação será exibida normalmente.
Avançada: a ação estará disponível, mas não será priorizada.
Interna: a ação ficará oculta.
Importante: a ação será priorizada e mostrada primeiro.
Por exemplo, se você importar uma definição de API aberta com 10 ações e não desejar que os usuários vejam/usem duas delas inicialmente, poderá selecionar a opção Interno para ocultá-las. Essa abordagem é uma maneira útil de lidar com operações usadas para oferecer suporte a metadados de conector dinâmico. Ela também permite ocultar as ações inicialmente e torná-las visíveis posteriormente, quando os usuários as solicitarem. Ocultar as ações limita o máximo possível a lista visível para os usuários.
As ações selecionadas como importantes são mostradas primeiro. O usuário precisa selecionar o conector para mostrar qualquer um selecionado como nenhum ou avançado. Essa abordagem é mais apropriada quando há várias ações e muitas não são usadas com frequência.
Solicitação
A solicitação define quais parâmetros/dados serão passados para a operação quando a ação chamar a operação na API. Quando você importar uma definição OpenAPI, ela configurará a consulta de solicitação, os cabeçalhos e as configurações do corpo. Também é possível importar manualmente importando da amostra.
A imagem a seguir mostra um exemplo da aparência da tela ao se olhar para a definição.
Essa configuração é importante porque se traduz no que o usuário vê ao usar a ação.
Editando cada um dos parâmetros ou fazendo com que o desenvolvedor da API forneça mais detalhes, você pode melhorar a experiência do usuário ao usar a ação. Selecionar as reticências (...) em cada parâmetro mostra a seguinte tela de edição.
Os campos e as opções que devem ser revisados e alterados são:
Nome: não altere; esse campo deve corresponder ao que a API espera.
Resumo: torne esse campo amigável, por exemplo, DatadeTérmino deve ser Data de Término.
Descrição: esse campo contém uma frase que descreve o parâmetro. Ele será usado como um texto de espaço reservado para o campo.
Valor padrão: esse campo é um valor padrão opcional, mas deve ser fornecido ao definir a visibilidade como interna e tornar o parâmetro obrigatório.
É obrigatório: certifique-se de definir essa opção se a API exigir um valor. Essa opção mostra um asterisco vermelho visual ao lado do campo.
Visibilidade: esse parâmetro funciona como a opção de visibilidade na ação abordada anteriormente. Se você tiver parâmetros que não são usados com frequência, selecione a opção avançado.
Tipo e Formato: verifique se esses campos são apropriados, pois o parâmetro que faz a importação dos exemplos faz suposições que nem sempre estão corretas.
Tipo de lista suspensa: use esse parâmetro para configurar uma lista estática ou dinâmica de valores para ajudar a tornar a seleção do usuário mais fácil e previsível.
A imagem a seguir mostra um exemplo de como seria a aparência da tela depois da correção do parâmetro A partir da data.
Resposta
A resposta define o que você espera que seja retornado da API. Diferentemente da solicitação, que tem uma única definição, você pode ter respostas diferentes com base no status HTTP. Por exemplo, se a chamada da API gerar um erro, o corpo conterá os detalhes do erro, em vez do resultado retornado pela API. Também é possível definir uma resposta padrão, que é uma resposta geral se não houver uma disponível para um status HTTP específico.
Selecionar uma das respostas revelará os detalhes e, semelhante ao processo com uma solicitação, você poderá editar esses itens para facilitar o consumo.
Os itens na resposta correspondem ao que é mostrado no painel Conteúdo dinâmico.
Semelhante à solicitação, verifique se você incluiu bons nomes e descrições, pois eles podem facilitar o uso dos valores.
Validação
Observe que uma seção de validação semelhante à seguinte imagem aparece na parte inferior da tela.
Verifique se essa tela não mostra erros e, em seguida, tome tempo para resolver os problemas listados.
Outras configurações
Também há outras configurações, como gatilhos, referências e políticas, que não são abordadas em detalhes neste módulo.
Os gatilhos podem ser configurados se a API der suporte a eventos de sondagem ou de webhook. Quando definidos, os gatilhos permitem o uso do conector como gatilho para um fluxo do Power Automate.
As referências definem parâmetros reutilizáveis e são normalmente criadas ao importar a definição e definir um parâmetro reutilizável. As referências também podem ser criadas com o uso do editor Swagger interno.
As políticas podem ser usadas para alterar os comportamentos de ações e gatilhos. As políticas são criadas usando um dos modelos de política predefinidos.
Esses tópicos avançados serão abordados em detalhes posteriormente neste roteiro de aprendizagem.
