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

Depois de concluir o desenvolvimento do conector personalizado, você precisa preparar os arquivos para certificação. Como um publicador verificado, siga estas etapas para preparar os arquivos para a certificação e depois gerar o conector e os arquivos de conector prontos para o agente, que serão enviados à Microsoft.

Passo 1: Cumprir os requisitos de submissão para conectores

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

Dê um título ao seu conector

O título deve satisfazer os seguintes requisitos:

• Tem de existir e ser escrito em inglês.
• Deve ser único e diferenciável de qualquer título de conector existente.
• Deve ter o nome do seu produto ou organização.
• Deve seguir os padrões de nomenclatura existentes para 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 carateres.
• Não é possível conter as palavras API, Connector Copilot Studio ou qualquer um dos nossos outros Power Platform nomes de produtos (por exemplo, Power Apps).
• Não pode terminar num caráter não alfanumérico, incluindo símbolo de retorno, nova linha ou espaço em branco.

Exemplos

• Bons títulos para conectores: Azure Sentinel*, *Office 365 Outlook
• Títulos de ligação fracos: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Escreva uma descrição para o seu conector

A descrição deve satisfazer os seguintes requisitos:

• Certifique-se de que a sua descrição está em conformidade com as diretrizes doMarketplace.
• Tem de existir e ser escrito em inglês.
• Não pode conter erros gramaticais e ortográficos.
• Deverá descrever o valor e a finalidade principal oferecidos pelo seu conector.
• Deve ter mais de 30 caracteres e menos de 500 caracteres.
• Não pode conter nenhum Copilot Studio ou outros Power Platform nomes de produtos (por exemplo, Power Apps).

Criar um ícone para o conector (aplicável apenas a editores verificados)

Esta secçã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).
• Utilize um fundo de cor não transparente, não-branco (#ffffff) e cor não predefinida (#007ee5) que corresponda à cor de fundo do ícone especificado.
• Certifique-se de que o ícone é exclusivo de qualquer outro ícone de conector certificado.
• Envie o logotipo no formato PNG como <icon>.png.
• Defina as dimensões do logótipo abaixo de 70% para a altura e largura da imagem com um fundo consistente.
• Certifique-se de que a cor da marca é uma cor hexadecimal válida e não deve ser branca (#ffffff) ou a predefinida (#007ee5).

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

Os resumos e descrições devem satisfazer os seguintes requisitos:

• Tem de existir e ser escrito em inglês.
• Não pode conter erros gramaticais e ortográficos.
• Os resumos de operação e parâmetros devem ser frases de 80 caracteres ou menos e conter apenas caracteres alfanuméricos ou parênteses.
• As descrições da operação e dos parâmetros devem ser frases completas e descritivas que terminam com pontuação.
• Não deve conter nenhum Copilot Studio ou outros nomes de produtos da Power Platform (por exemplo, Power Apps).

Definir respostas de operação exatas

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

• Defina as respostas de operação com um esquema exato apenas com respostas esperadas.
• Não use respostas predefinidas com a definição exata de um esquema.
• Fornecer definições de esquema de resposta válidas para todas as operações no swagger.
• Não são permitidos esquemas de resposta vazios, exceto em casos especiais em que o esquema de resposta é dinâmico. Isto significa que nenhum conteúdo dinâmico é mostrado na saída e os criadores têm de usar JSON para analisar a resposta.
• Não são permitidas operações vazias.
• Remova as propriedades vazias, a menos que sejam obrigatórias.

Verificar as propriedades do swagger

As propriedades devem atender aos seguintes requisitos:

• Verifique se o openapidefinition.json está em um arquivo JSON formatado corretamente.
• Certifique-se de que a definição do swagger esteja em conformidade com o padrão OpenAPI Specification v2.0 e o padrão estendido dos conectores.

Verificar parâmetros de ligação

Os parâmetros devem satisfazer os seguintes requisitos:

• Verifique se a propriedade está atualizada com os valores apropriados para uiDefinition (nome para exibição, descrição).

• Se o parâmetro de ligação utilizar autenticação Básica, certifique-se de que o JSON está formatado corretamente como o seguinte exemplo.

  {
    "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 parâmetro de ligação tiver APIKey como autenticação, certifique-se de que o JSON está formatado corretamente como o seguinte exemplo.

  {
    "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 Generic OAuth como autenticação, verifique se o JSON está formatado corretamente como o 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 parâmetro de ligação tiver fornecedor de identidade OAuth2, certifique-se de que o fornecedor de identidade faz parte da lista de fornecedores OAuth2 suportados. Aqui está um exemplo do fornecedor de identidade GitHub OAuth2:

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

• Se o parâmetro de ligação tiver Microsoft Entra ID como autenticação, certifique-se de que o JSON está formatado corretamente como o seguinte exemplo.

  {
    "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
    }
  }
  

Criar cadeias de idioma em inglês de qualidade

Os conectores são localizados como parte da localização do Power Automate; portanto, quando desenvolve um conector, a qualidade das cadeias do idioma inglês é fundamental para a qualidade da tradução. Aqui estão algumas áreas importantes a abordar à medida que cria os valores das cadeias que fornece.

• Execute um programa de verificação ortográfica para garantir que todos os valores de cadeia de caracteres estejam livres de erros tipográficos. Se houver uma cadeia do idioma inglês incompleta, o resultado da tradução é incompleto ou incorreto no contexto.

• Certifique-se de que a frase está na forma completa, o que significa que tem pelo menos um sujeito e um predicado. Se a frase não estiver completa, isso também pode gerar traduções de menor qualidade.

• Certifique-se de que o significado da frase é claro. Se o significado da frase for ambíguo, isso também pode gerar traduções de menor qualidade ou incorretas.

• Certifique-se de que os resumos, os resumos x-ms e as descrições estão gramaticalmente corretos. Não copie e cole os resumos. Para saber como eles são exibidos no produto, vá para Orientação da cadeia de caracteres do conector.

• Evite cadeias compostas de runtime, se possível. Use frases totalmente formadas. As cadeias ou frases concatenadas dificultam a tradução, ou podem levar a uma tradução errada.

• Certifique-se de colocar as abreviaturas em maiúsculas para torná-las claras. A utilização de maiúsculas reduz a probabilidade de ser confundida com um erro tipográfico.

• Corrija as cadeias de caracteres de formulário CAlMel se quiser localizar o valor da cadeia de caracteres. Strings na forma CaMel (por exemplo, minimizeHighways ou MinimizeHighways) são normalmente consideradas não traduzíveis.

Passo 2: Executar o Verificação de Soluções para validar o conector

O Solution Checker é um mecanismo para conduzir análises estáticas para garantir que seu conector esteja de acordo com os padrões de certificação da 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 o verificador de soluções para executar o verificador de soluções.

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

Etapa 3: Atender aos requisitos de envio para ações do conector

Certifique-se de que as ações do conector sigam estas diretrizes:

• As diretrizes de IA responsável descrevem o que todos os conectores preparados para 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 pelos quais todos os conectores preparados para agentes devem estar em conformidade. As ações do 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 aprender como os conectores são ferramentas que ampliam a funcionalidade do Microsoft Copilot Studio.

Etapa 4: Preparar o conector e os artefatos relacionados

Você envia um conjunto de arquivos para a Microsoft, que provém de uma geração de solução no portal do criador ou no Microsoft Copilot Studio. Para empacotar seus arquivos, siga as etapas nesta secção.

Empacote seus arquivos de conector

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

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

3. Exportar a solução de conector.

4. Crie um fluxo de teste usando o conector personalizado recém-criado ou adicione um fluxo existente à solução.

5. Exportar 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 no seguinte formato:

   

Nota

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 ficheiros dentro da solução.

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

Tanto editores verificados quanto editores independentes baixam 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 como #da3b01 no arquivo openapidefinition.
  

Criar um artefacto intro.md.

Um ficheiro intro.md é necessário tanto para editores independentes como para editores verificados. Precisa de criar um ficheiro intro.md para documentar as funcionalidades do seu conector. Para obter um exemplo de documentação a ser incluída, vá para o exemplo Readme.md. Para saber como escrever um arquivo intro.md, veja 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 a estrutura

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

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

1. Abra o Windows PowerShell no modo Admin.

   

2. Altere o local da unidade digitando cd /.

   O exemplo a seguir usa C:\.

   

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

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

   

4. Defina a política de execução como irrestrita inserindo o seguinte comando:

   Set-ExecutionPolicy -ExecutionPolicy Unrestricted

   

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

5. Confirme a sua entrada introduzindo Y, que significa Sim.

6. Execute o script ConnectorPackageValidator.ps1 introduzindo o caminho para o ficheiro 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 detetando e destacando os defeitos na estrutura do pacote.

   

Etapa 6: Enviar seu conector para certificação

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

1. (Para editores independentes) Para enviar o pacote à Microsoft para certificação, siga as instruções no processo de Certificação de 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 for um editor verificado, tem de submeter um ficheiro script.csx se estiver a utilizar código personalizado.

   Se o conector tiver OAuth, forneça ID do Cliente e Segredo no Partner Center. Além disso, obtenha o APIname do seu pedido de submissão de conector para atualizar a sua aplicação.

   Como parte da submissão, a Microsoft certifica e/ou cria um plug-in do conector. Se você precisar solucionar erros de swagger, vá para Corrigir erros do Swagger Validator.

Lista de verificação antes de submeter

Antes de passar para Enviar seu conector para certificação Microsoft, verifique se:

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

• Nenhuma operação está a faltar 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 validação de tempo de execução ou esquema aparece na secção de teste do assistente de conector personalizado.

Para questões relacionadas com a certificação

Você precisa ter que Microsoft Teams participar da reunião de Horário de Escritório. Se precisar de acesso, veja as suas opções em Microsoft Teams.

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

Próximo passo

• Processo de certificação de editor verificado
• Processo de certificação de editores independentes