Compartilhar via

Preparar o conector do Power Platform e os arquivos de plug-in para certificação

  • Artigo

Este processo é tanto para editores independentes quanto verificados.

Depois de concluir o desenvolvimento do conector e/ou do plug-in personalizado, siga estas etapas a fim de prepará-lo para certificação e gerar os arquivos do conector e/ou do plug-in a serem enviados à Microsoft.

Observação

Este artigo apresenta informações para certificação de conectores personalizados em Aplicativos Lógicos do Azure, no Power Automate e em plug-ins do Power Apps no Copilot. Antes de seguir as etapas neste artigo, leia Certifique o conector e/ou o plug-in.

Etapa 1: registrar o conector e/ou o plug-in (só aplicável para editores independentes)

Esta seção não se aplica a editores verificados.

Você não precisa concluir o desenvolvimento no conector personalizado e/ou no plug-in para solicitar certificação. Para iniciar o processo de certificação, registre o conector e/ou o plug-in de certificação preenchendo nosso formulário de registro.

Aguarde um email dentro de dois dias úteis de um contato da Microsoft, que:

  • Compreende o conector e/ou o plug-in personalizado.
  • Aprende mais sobre o progresso de desenvolvimento.
  • Envia um email para você sobre o processo de certificação.

Etapa 2: atender aos requisitos de envio dos conectores

Para manter um alto padrão de qualidade e consistência entre nossos conectores certificados, a Microsoft possui um conjunto de requisitos e diretrizes que seu conector personalizado deve seguir para obter a certificação.

Dar um título ao seu conector

O título deve atender aos requisitos a seguir.

  • Deve existir e ser escrito em inglês.
  • Deve ser exclusivo e distinguível de qualquer título de conector e/ou plug-in existente.
  • Deve ser o nome do seu produto ou organização.
  • Deve seguir os padrões de nomenclatura existentes para conector e/ou plug-in certificado. Para editores independentes, o nome do conector deve seguir o padrão Connector and/or plugin Name (Independent Publisher).
  • Não pode ter mais de 30 caracteres.
  • Não pode conter as palavras API, Conector ou qualquer um de nossos nomes de produtos do Power Platform (por exemplo, Power Apps)
  • Não pode terminar com um caractere não alfanumérico, incluindo retorno de carro, nova linha ou espaço em branco.

Exemplos

  • Títulos de conector e/ou plug-in satisfatórios: Azure Sentinel*, *Office 365 Outlook
  • Títulos de conector e/ou plug-in insatisfatórios: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Escreva uma descrição para o seu conector

A descrição deve atender aos requisitos a seguir.

  • Deve existir e ser escrito em inglês.
  • Deve estar livre de erros gramaticais e ortográficos.
  • Deve descrever de forma concisa o principal objetivo e o valor oferecidos pelo seu conector.
  • Não pode ter menos de 30 caracteres nem mais de 500 caracteres.
  • Não pode conter nenhum nome de produto do Power Platform (por exemplo, "Power Apps").

Criar um ícone para o conector (só aplicável para editores verificados)

Essa seção não se aplica a editores independentes.

  • Crie um logotipo com dimensões 1:1 dentro de um intervalo de 100 x 100 a 230 × 230 pixels (sem bordas arredondadas).
  • Use um plano de fundo não transparente e não branco (#ffffff) e uma cor não padrão (# 007ee5) que corresponda à cor de plano de fundo do ícone especificada.
  • Certifique-se de que o ícone seja exclusivo para qualquer outro ícone de conector certificado.
  • Envie o logotipo em formato PNG como <icon>.png.
  • Defina as dimensões do logotipo abaixo de 70% para a altura e a largura da imagem com um plano de fundo consistente.
  • Certifique-se de que a cor da marca seja hexadecimal válida e não que não seja branca (#ffffff) ou padrão (#007ee5).

Definir resumos e descrições de operação e parâmetros

Os resumos e as descrições devem atender aos requisitos a seguir.

  • Deve existir e ser escrito em inglês.
  • Deve estar livre de erros gramaticais e ortográficos.
  • Os resumos de operação e parâmetro devem ser frases de 80 caracteres ou menos e só conter caracteres alfanuméricos ou parênteses.
  • Descrições de operação e parâmetro devem ser completas, descritivas e conter a pontuação final.
  • Não pode conter nenhum nome de produto do Microsoft Power Platform (por exemplo, "Power Apps").

Defina as respostas de operação exatas

As respostas de operação devem atender aos requisitos a seguir.

  • Defina as respostas da operação com um esquema exato apenas com as respostas esperadas.
  • Não use respostas padrão com uma definição de esquema exata.
  • Fornece definições de esquema de resposta válidas para todas as operações no swagger.
  • Esquemas de resposta vazios não são permitidos, exceto em casos especiais em que o esquema de resposta é dinâmico. Isso significa que nenhum conteúdo dinâmico será mostrado na saída e os criadores devem usar JSON para analisar a resposta.
  • Operações vazias não são permitidas.
  • Remova as propriedades vazias, a menos que sejam necessárias.

Verificar as propriedades do swagger

As propriedades devem atender aos requisitos a seguir.

  • Certifique-se de que "openapidefinition" esteja em um arquivo JSON formatado corretamente.
  • Certifique-se de que a definição do swagger esteja em conformidade com o padrão OpenAPI 2.0 e o padrão estendido dos conectores.

Verificar os parâmetros da conexão

Os parâmetros devem atender aos requisitos a seguir.

  • Certifique-se de que a propriedade esteja atualizada com os valores apropriados para "UIDefinition" (nome de exibição, descrição).

  • Se o seu parâmetro de conexão usar autenticação Básica, certifique-se de que o JSON esteja formatado corretamente como no exemplo a seguir.

    {
  "username": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourUsernameLabel",
      "description": "The description of YourUsernameLabel for this api",
      "tooltip": "Provide the YourUsernameLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": true,
        "required": "true"
        }
  }
},
  "password": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourPasswordLabel",
      "description": "The description of YourPasswordLabel for this api",
      "tooltip": "Provide the YourPasswordLabel tooltip text",
      "constraints": {
        "tabIndex": 3,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Se o seu parâmetro de conexão tiver a APIKey como autenticação, certifique-se de que o JSON esteja formatado corretamente como no exemplo a seguir.

    {
  "api_key": {
    "type": "securestring",
    "uiDefinition": {
      "displayName": "YourApiKeyParameterLabel",
      "tooltip": "Provide your YourApiKeyParameterLabel tooltip text",
      "constraints": {
        "tabIndex": 2,
        "clearText": false,
        "required": "true"
      }
    }
  }
}

  • Se o seu parâmetro de conexão tiver o OAuth Genérico como autenticação, certifique-se de que o JSON esteja formatado corretamente como no exemplo a seguir.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "oauth2",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "AuthorizationUrl": {
          "value": "https://contoso.com"
        },
        "TokenUrl": {
          "value": "https://contoso.com"
        },
        "RefreshUrl": {
          "value": "https://contoso.com"
        }
      },
      "clientId": "YourClientID"
    },
    "uiDefinition": null
  }
}

  • Se o seu parâmetro de conexão tiver um provedor de identidade OAuth2, certifique-se de que o provedor de identidade esteja na lista de provedores OAuth2 compatíveis. Veja a seguir o exemplo do provedor de identidade OAuth2 do GitHub:

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "github",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {},
      "clientId": "YourClientId"
    },
    "uiDefinition": null
  }
}

  • Se o seu parâmetro de conexão tiver o Microsoft Entra ID como autenticação, certifique-se de que o JSON esteja formatado corretamente como no exemplo a seguir.

    {
  "token": {
    "type": "oAuthSetting",
    "oAuthSettings": {
      "identityProvider": "aad",
      "scopes": [
        "scope1"
      ],
      "redirectMode": "GlobalPerConnector",
      "customParameters": {
        "LoginUri": {
          "value": "https://login.microsoftonline.com"
        },
        "TenantId": {
          "value": "common"
        },
        "ResourceUri": {
          "value": "resourceUri"
        },
        "EnableOnbehalfOfLogin": {
          "value": false
        }
      },
      "clientId": "AzureActiveDirectoryClientId"
    },
    "uiDefinition": null
  }
}

Crie cadeias de caracteres de qualidade em inglês

Os conectores são localizados como parte da localização do Power Automate. Por isso, quando você desenvolve um conector, a qualidade das cadeias de caracteres do idioma inglês é fundamental para a qualidade da tradução. Veja algumas das principais áreas para focar durante a criação de valores das cadeias de caracteres que você fornecer.

  • Para garantir que todos os valores da cadeia de caracteres não tenham erros tipográficos, execute um programa de verificação ortográfica. Se houver alguma cadeia de caractere incompleta em inglês, o resultado da tradução ficará incompleto ou incorreto no contexto.

  • Certifique-se de que a frase esteja completa. Se a frase não estiver completa, isso também poderá gerar traduções de menor qualidade.

  • Verifique se o significado da frase está claro. Se o significado da frase for ambíguo, isso também poderá gerar menos qualidade ou traduções incorretas.

  • Certifique-se de que resumos, resumos x-ms e descrições estejam gramaticalmente corretos. Não os copie e cole. Para saber como eles são exibidos no produto, acesse Diretriz de cadeia de caracteres de conector.

  • Evite cadeias de caracteres compostas em runtime, se possível. Em vez disso, use frases totalmente formadas. Cadeias de caracteres ou frases concatenadas dificultam a tradução ou podem causar um erro na tradução.

  • Se você usar abreviações, captalize-as para deixar o significado claro. Isso reduzirá a chance de ser confundido com um erro tipográfico.

  • As cadeias de caracteres na forma CaMel (por exemplo, minimizeHighways ou MinimizeHighways) costumam ser consideradas não traduzíveis. Se quiser localizar o valor da cadeia de caractere, você deve corrigir a cadeia de caractere do formulário CaMel.

Etapa 3: usar o verificador de solução para validar seu conector

O verificador de solução é um mecanismo para realizar análises estáticas para garantir que seu conector esteja em conformidade com os padrões exigidos pela Microsoft para certificação. Adicione seu conector a uma solução no Power Automate ou no Power Apps e execute o verificador de solução seguindo as instruções em Validar um conector personalizado com o verificador de solução.

Assista a este vídeo para saber como executar o verificador de solução.

Etapa 4: adicionar metadados

Os artefatos (arquivos) do conector devem conter metadados específicos que descrevem o conector e seu serviço final. As informações fornecidas nos metadados serão publicadas na documentação do conector e poderão ser publicamente acessadas por todos os usuários. Não forneça nenhuma informação privada ou confidencial e nos avise por meio do seu contato da Microsoft caso haja algum problema para fornecer essas informações. Para saber como os metadados serão documentados, acesse qualquer uma das páginas de documentação específicas do conector em Referência do conector.

Etapa 4a: propriedades publisher e stackOwner

  • "editor" é o nome da sua empresa ou organização. Forneça o nome completo da empresa (por exemplo, "Contoso Corporation"). Isso deve estar no formato alfanumérico.
  • "stackOwner" é a empresa ou a organização proprietária da pilha de serviços back-end à qual o conector está se ligando. Isso deve estar no formato alfanumérico.
Editor Descrição Exemplo
Verificada O editor e o stackOwner serão os mesmos, a menos que o ISV esteja criando um conector em nome de um stackOwner. "editor": "Tesla",
"stackOwner": "Tesla"
Independente Você deve fornecer o proprietário da pilha e o proprietário do editor. "editor": "Nirmal Kumar",
"stackOwner": "ITGlue"

Local do arquivo: apiProperties.json
Para saber mais, vá para Arquivo de propriedades da API.

Sintaxe: As propriedades publisher e stackOwner existem como propriedades de nível superior dentro do arquivo apiProperties.json. Adicione as seguintes linhas destacadas como mostrado. Não se esqueça de inserir o nome da propriedade e o esquema exatamente conforme mostrado.

Captura de tela mostrando as propriedades publisher e stackOwner, disponíveis em trechos de código da amostra.

Etapa 4c: trechos de código de amostra

É possível usar os trechos de código a seguir para copiar e inserir as informações. Não se esqueça de adicionar os trechos aos arquivos corretos nos locais corretos, conforme descrito na seção anterior.

    "publisher": "_____",
    "stackOwner": "_____"

    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }

    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

Observação

Existe uma limitação atual quanto ao uso da propriedade stackOwner e da ferramenta de CLI Paconn. Para saber mais, vá até Limitações no arquivo README.

Etapa 4d: formatação e limitações do arquivo JSON

  • Certifique-se de que suas propriedades estejam alinhadas corretamente.

  • Cole seu JSON no Visual Studio Code. Sinta-se à vontade para usar extensões como corretores ortográficos e plug-ins como plug-ins JSON.

  • Os arquivos swagger não devem ter mais de 1 MB.

    • Considere o design do seu conector antes de começar a criá-lo. Avalie se o conector deve ser dividido em dois (2) ou mais conectores.
    • Arquivos swagger maiores podem causar um atraso ao usar o conector.

    Por exemplo, existem três (3) conectores HubSpot diferentes na plataforma.

    Captura de tela de pastas para os três conectores do HubSpot.

Etapa 4e: validar seus arquivos de conector personalizados

Execute a paconn validate --api-def [Location of apiDefinition.swagger.json]. Essa ferramenta validará a definição de seu conector e informará sobre os erros que você deverá corrigir antes de enviar.

Caso o conector use OAuth como tipo de autenticação, adicione essas URLs de redirecionamento permitidas ao aplicativo:

  • https://global.consent.azure-apim.net/redirect/{apiname}

  • https://global-test.consent.azure-apim.net/redirect/{apiname}

Etapa 5: atender aos requisitos de envio dos plug-ins

Esta seção se aplicará se você também estiver enviando o plug-in do conector associado para certificação.

Etapa 6: Preparar os artefatos de conector e/ou plug-in

Observação

  • Verifique se você seguiu as especificações e garantiu a qualidade do conector e/ou do plug-in antes da certificação. Não fazer isso resultará em atrasos na certificação porque será solicitado que você faça alterações.
  • Forneça uma versão de produção da URL do host. URLs de host de preparo, desenvolvimento e teste não são permitidos.

Você está enviando para a Microsoft um conjunto de arquivos, baixado usando-se uma ferramenta de interface de linha de comando (CLI) fornecida pela Microsoft. Esta ferramenta validará seu conector quanto a erros de quebra.

Siga estas etapas para começar:

  1. Instale a ferramenta CLI Conectores do Microsoft Power Platform seguindo as instruções de instalação.

  2. Entre no Microsoft Power Platform usando a linha de comando executando paconn login. Siga as instruções para entrar usando o processo do código de dispositivo da Microsoft.

  3. Depois de fazer a autenticação, baixe os arquivos de conector personalizados:

    • Execute a paconn download. Selecione o ambiente em que seu conector personalizado está localizado especificando o número na linha de comando e, em seguida, selecione o nome do conector personalizado.

    A ferramenta baixa os artefatos de conector e/ou plug-in em uma pasta no local do sistema de arquivos onde você executou paconn. Dependendo do tipo de editor, você encontrará vários artefatos:

Guia de empacotamento do conector e do plug-in

Os procedimentos nesta seção orientam você em meio a cenários variados de empacotamento. Use o primeiro cenário se você só quiser empacotar um conector personalizado. Use o segundo cenário se você quiser empacotar um conector personalizado e os plug-ins. Use o último cenário se você quiser empacotar um conector existente e os plug-ins.

Empacotar o conector personalizado e enviar para certificação

  1. Crie um conector personalizado para uma solução.

  2. Execute o verificador de solução na solução do conector na etapa 1.

  3. Exporte a solução do conector.

  4. Crie um fluxo (teste) usando o conector personalizado recém-criado e adicione o fluxo a uma solução.

  5. Exporte a solução do fluxo.

  6. Crie um pacote com as soluções das etapas 3 e 5.

  7. Crie um arquivo intro.md.

  8. Crie o pacote final como um arquivo zip, que está no seguinte formato:

    Captura de tela das pastas e dos arquivos em um arquivo zip de um conector certificado a ser certificado.

  9. Carregue o pacote em um blob de armazenamento e gere a URL SAS.

  10. Envie o pacote para o Partner Center.

Empacotar o conector personalizado e o plug-in para certificação

  1. Siga as etapas de 1 a 5 em Empacotar o conector personalizado e enviar para certificação neste artigo.

  2. Crie um plug-in no portal do Microsoft Copilot Studio e o exporte como uma solução.

  3. Crie um pacote a partir do seguinte:

  4. Crie um arquivo intro.md.

  5. Crie o pacote final como um arquivo zip, que está no seguinte formato.

    Captura de tela das pastas e dos arquivos em um arquivo zip de um conector certificado e plug-in a ser certificado.

Empacotar o conector certificado existente e o plug-in para certificação

  1. Crie uma solução no Power Automate e adicione o conector já certificado a ela.

  2. Siga as etapas de 2 a 4 em Empacotar o conector personalizado e enviar para certificação neste artigo.

  3. Crie um plug-in no Copilot Studio e o exporte como uma solução.

  4. Exporte o plug-in como solução.

  5. Crie um pacote a partir do seguinte:

  6. Crie um arquivo intro.md.

  7. Crie o pacote final como um arquivo zip, que está no seguinte formato.

    Captura de tela das pastas e dos arquivos em um arquivo zip de um conector certificado existente e plug-in a ser certificado.

Tanto os editores verificados quanto os independentes baixarão apiProperties.json em seus artefatos. Você precisa definir o IconBrandColor neste arquivo.

  • Editores verificados: defina iconBrandColor como a cor da marca no arquivo apiProperties.
  • Editores independentes: defina iconBrandColor como "#da3b01" no arquivo apiProperties.
    Captura de tela de um ícone laranja vívido (da3b01).

Criar um artefato intro.md

Um arquivo intro.md é necessário para editores independentes e verificados. Você precisa criar um arquivo intro.md para documentar os recursos e a funcionalidade do conector. Para obter um exemplo de documentação a ser incluída, vá para o exemplo de Readme.md. Para saber como escrever um arquivo intro.md, observe outros arquivos intro.md (também conhecidos como arquivos Readme.md) em nosso repositório do GitHub.

Se você for um editor independente e seu conector usar OAuth, certifique-se de incluir instruções sobre como obter credenciais.

Dica

Problemas e limitações conhecidos é uma ótima seção para manter seus usuários atualizados.

Etapa 7: Enviar o conector e/ou o plug-in para certificação

Durante o processo de envio, você abre o código do conector e/ou o plug-in para nosso Repositório de conectores do Microsoft Power Platform.

  1. (Para editores independentes) Para enviar o pacote à Microsoft para certificação, siga as instruções em Processo de certificação do editor independente.

  2. (Para editores verificados) Para enviar o pacote à Microsoft para certificação no Partner Center, siga as instruções em Processo de certificação do editor verificado.

    Se você for um editor verificado, será necessário enviar um arquivo script.csx se estiver usando código personalizado.

    Se o conector tiver OAuth, forneça a ID do Cliente e o Segredo no Partner Center. Além disso, obtenha o nome da API da solicitação de envio do conector para atualizar o aplicativo.

    Como parte do envio, a Microsoft certifica o conector e/ou o plug-in. Se você precisar solucionar erros de swagger, vá para Corrigir erros do Validador Swagger.

Lista de verificação antes de enviar

Antes de passar para Enviar seu conector para certificação da Microsoft, certifique-se de que:

Dica

  • Crie vídeos, blogs ou outro conteúdo do YouTube para compartilhar amostras ou capturas de tela de introdução do conector e/ou do plug-in.
  • Inclua os links no arquivo intro.md, de maneira que possamos adicionar aos documentos.
  • Adicione dicas de ferramentas ao seu arquivo swagger para ajudar seus usuários a serem mais bem-sucedidos.

Próxima etapa