Preparar arquivos de conector do Agente e do Power Platform para certificação

Depois de concluir o desenvolvimento do conector personalizado, você precisará preparar os arquivos para certificação. Como um editor verificado, siga estas etapas a fim de preparar os arquivos para certificação e gerar o conector e os arquivos do conector prontos para uso pelo agente que você enviar à Microsoft.

Etapa 1: atender aos requisitos de envio dos conectores

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

Dê 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 existente.
• Deve ser o nome do seu produto ou organização.
• Deve seguir os padrões de nomenclatura existentes para o conector certificado. Para editores independentes, o nome do conector deve seguir o padrão Connector Name (Independent Publisher).
• Não pode ter mais de 30 caracteres.
• Não é possível conter as palavras API, Connector, Copilot Studio ou qualquer um de nossos outros 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

• Bons títulos de conector: Azure Sentinel*, *Office 365 Outlook
• Títulos do conector inadequados: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Escreva uma descrição para o seu conector

A descrição deve atender aos seguintes requisitos:

• Verifique se sua descrição está em conformidade com as Diretrizes do Marketplace.
• 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.
• Deve ser maior que 30 caracteres e menor que 500 caracteres.
• Não é possível conter nenhum Copilot Studio ou outros nomes de produtos do Power Platform (por exemplo, Power Apps).

Desenhe um ícone para o seu conector (apenas aplicável para editores verificados)

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

• Crie um logotipo com dimensões 1:1 em 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 um hexadecimal válido e 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 seguintes requisitos:

• 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.
• As descrições de operação e parâmetro devem ser frases completas e descritivas que terminam com pontuação.
• Não deve conter nenhum Copilot Studio ou outros nomes de produtos do Power Platform (por exemplo, Power Apps).

Defina as respostas de operação exatas

As respostas de operação devem atender aos seguintes requisitos:

• Defina as respostas da operação utilizando um esquema exato somente para as respostas esperadas.
• Não use respostas padrão com uma definição de esquema exata.
• Forneça 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.json está em um arquivo JSON formatado corretamente.
• Verifique se a definição de Swagger está em conformidade com o padrão OpenAPI Specification v2.0 e o padrão estendido dos conectores.

Verificar os parâmetros da conexão

Os parâmetros devem atender aos seguintes requisitos:

• Verifique se a propriedade está atualizada com os valores apropriados para uiDefinition (nome para 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 parâmetro de conexão tiver OAuth Genérico como autenticação, verifique se o JSON está 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. Aqui está um exemplo de provedor de identidade OAuth2 do GitHub:

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

• Se o parâmetro de conexão tiver Microsoft Entra ID como autenticação, verifique se o JSON está 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. Assim, ao desenvolver 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.

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

• Verifique se a frase está em forma completa, o que significa que ela tem pelo menos um assunto e um predicado. 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 copie e cole os resumos. Para saber como eles são mostrados no produto, acesse Guia de cadeia de conexão.

• 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.

• Certifique-se de usar letras maiúsculas em abreviações para torná-las mais claras. O uso de letras maiúsculas reduz a chance de a abreviação ser confundida com um erro tipográfico.

• Corrija as strings em formato CAlMel se quiser localizar o valor da cadeia de caracteres. As cadeias de caracteres no formato CaMel (por exemplo, minimizeHighways ou MinimizeHighways) geralmente são consideradas não traduzíveis.

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

Verificador de Solução é um mecanismo para conduzir análises estáticas para garantir que seu conector siga os padrões de certificação Microsoft. Adicione o conector a uma solução em Power Automate ou Power Apps e siga as instruções em Validar um conector personalizado com verificador de solução para executar o verificador de solução.

Assista a este vídeo para saber como executar o Verificador de Solução.

Etapa 3: cumprir os requisitos de envio para ações do conector

Verifique se as ações do conector seguem estas diretrizes:

• As diretrizes de IA responsável descrevem o que todos os conectores prontos para uso por agentes precisam seguir.
• 100.10 Conteúdo inadequado destaca uma seção nos Termos de Uso do Microsoft Commercial Marketplace que descreve os padrões com os quais todos os conectores prontos para agente devem estar em conformidade. As ações de conector não devem gerar, conter ou fornecer acesso a conteúdo inapropriado, prejudicial ou ofensivo gerado por IA.
• Use conectores no Copilot Studio para entender como os conectores funcionam como ferramentas que estendem a funcionalidade do Microsoft Copilot Studio.

Etapa 4: Preparar o conector e artefatos relacionados

Você envia um conjunto de arquivos para a Microsoft, que é uma solução gerada a partir do Portal do Criador ou do Microsoft Copilot Studio. Para empacotar seus arquivos, siga as etapas nesta seção.

Empacote seus arquivos do conector

1. Criar um conector personalizado em 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. Criar um fluxo de teste usando o conector personalizado recém-criado ou adicionar um fluxo existente à solução.

5. Exporte a solução de 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 no seguinte formato:

   

Observação

Os nomes da pasta e dos arquivos fora da solução são apenas para referência, você pode escolher de acordo com suas necessidades. No entanto, não manipule os arquivos dentro da solução.

9. Carregue o pacote em um blob de armazenamento e gere a URL SAS. Verifique se a URI do SAS é válida por pelo menos 15 dias.
10. Envie o pacote para o Partner Center.

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

• Editores verificados: defina iconBrandColor para a cor da sua marca no arquivo openapidefinition.
• Editores independentes: defina iconBrandColor para #da3b01 no arquivo openapidefinition.
  

Criar um artefato chamado 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 mais sobre como escrever um arquivo intro.md, examine outros arquivos intro.md (também conhecidos como arquivos Readme.md) em nosso repositório GitHub.

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

Etapa 5: Validar o pacote para estrutura

O script de validação do pacote valida a estrutura do pacote e ajuda você a gerar o pacote em um formato aceitável para certificação. Baixe o script do validador de pacote, ConnectorPackageValidator.ps1.

Para executar o script de validação de pacote, siga estas etapas:

1. Abra Windows PowerShell no modo administrador.

   

2. Altere o local da unidade digitando cd /.

   O exemplo a seguir usa C:\.

   

3. Vá para o caminho onde você baixou o script validador de pacote.

   Por exemplo, se o caminho for C:\Users\user01\Downloads, você digita cd .\Users\user01\Downloads\.

   

4. Defina a diretiva de execução como irrestrita digitando o seguinte comando:

   Set-ExecutionPolicy -ExecutionPolicy Unrestricted

   

   Este comando permite que o PowerShell seja executado sem qualquer restrição.

5. Confirme sua entrada digitando S, que significa Sim.

6. Execute o ConnectorPackageValidator.ps1 inserindo o caminho do arquivo zip que contém o pacote do conector.

   Como mostrado no exemplo a seguir, o primeiro argumento é um caminho de arquivo zip válido que contém o pacote.

   

   Se a estrutura do pacote estiver correta, a seguinte mensagem de êxito será exibida:

   

   Se houver um problema com a estrutura do pacote, o script fornecerá detalhes do problema detectando e destacando os defeitos na estrutura do pacote.

   

Etapa 6: Enviar seu conector para certificação

Durante o processo de envio, você abre o conector para nosso repositório Microsoft Power Platform Connectors.

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 APIname da solicitação de envio do conector para atualizar o aplicativo.

   Como parte do envio, a Microsoft certifica e/ou integra o seu conector. 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:

• Seu conector personalizado atende a todos os padrões definidos na Etapa 1: atender aos requisitos de envio para conectores e Etapa 3: atender aos requisitos de envio para ações do conector.

• Nenhuma operação está sem resumo, descrição ou informações de visibilidade.

• Você testou seu conector personalizado para garantir que as operações funcionem conforme o esperado (pelo menos 10 chamadas bem-sucedidas por operação).

• Nenhum erro de execução ou de validação de esquema aparece na seção de teste do assistente personalizado de conector.

Para consultas sobre certificação

Você precisa ter Microsoft Teams para ingressar na reunião do Office Hours. Se precisar de acesso, exiba suas opções em Microsoft Teams.

Participe da Reunião do Horário de Atendimento todas as terças-feiras, das 15h30 às 16h30, UTC (Horário Universal Coordenado).

Próxima etapa

• Processo de certificação de editor verificado
• Processo de certificação de editor independente