Partilhar via

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

  • Artigo

Este processo é tanto para editores verificados como independentes.

Depois de concluir o desenvolvimento do seu conector e/ou plug-in personalizado, siga estes passos para o preparar para certificação e gerar os ficheiros do conector e/ou ficheiros de plug-in a submeter à Microsoft.

Nota

Este artigo fornece informações para a certificação de conectores personalizados no Azure Logic Apps, Power Automate e Power Apps e plugins no Copilot. Antes de seguir os passos deste artigo, leia Certificar o seu conector e/ou plug-in.

Passo 1: Registar o seu conector e/ou plug-in (apenas aplicável a editores independentes)

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

Não tem de concluir o desenvolvimento do conector e/ou plug-in personalizado para solicitar a certificação. Para iniciar o processo de certificação, registe o seu conector e/ou plug-in para certificação preenchendo o nosso formulário de registo.

Espere um e-mail dentro de dois dias úteis a partir de um contacto da Microsoft, que:

  • Compreende o seu conector personalizado, conector e/ou plug-in.
  • Aprende sobre o progresso do seu desenvolvimento.
  • Envia-lhe e-mails sobre o processo de certificação.

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

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

Dê um título ao seu conector

O título tem de cumprir os seguintes requisitos.

  • Tem de existir e ser escrito em inglês.
  • Tem de ser exclusivo e distinto de qualquer título de conector e/ou plug-in existente.
  • Deve ter o nome do seu produto ou organização.
  • Deve seguir os padrões de nomeação existentes para o 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 carateres.
  • não pode conter as palavras API, Conector nem nenhum dos nossos nomes de produtos do Power Platform (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 de conector e/ou plug-in: Azure Sentinel*, *Office 365 Outlook
  • Maus títulos de conector e/ou plug-in: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Escreva uma descrição para o seu conector

A descrição deve cumprir os seguintes requisitos.

  • 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.
  • Não pode ter menos que 30 carateres ou mais que 500 carateres.
  • Não pode conter nomes de produtos do Power Platform (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 logótipo do com dimensões 1:1 num intervalo de 100 x 100 a 230 × 230 pixeis (sem extremidades 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.
  • Submeta o logótipo 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 cumprir os seguintes requisitos.

  • Tem de existir e ser escrito em inglês.
  • Não pode conter erros gramaticais e ortográficos.
  • Resumos de operações e parâmetros devem ser expressões de 80 carateres ou menos, e conter apenas carateres alfanuméricos ou parênteses.
  • Descrições de operações e de parâmetros devem ser frases completas, descritivas, e terminar em pontuação.
  • Não pode conter quaisquer nomes de produtos do Microsoft Power Platform (por exemplo, "Power Apps").

Definir respostas de operação exatas

As respostas de operação devem cumprir os 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 cumprir os seguintes requisitos.

  • Certifique-se de que a "openapidefinition" está num ficheiro JSON corretamente formatado.
  • Garanta que a definição do swagger está em conformidade com o padrão OpenAPI 2.0 e com o padrão expandido dos conectores.

Verificar parâmetros de ligação

Os parâmetros devem cumprir os seguintes requisitos.

  • Certifique-se de que a propriedade é atualizada com valores apropriados para "UIDefinition" (nome a apresentar, 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 ligação tiver Generic OAuth como autenticação, certifique-se de que o JSON está formatado corretamente como o seguinte exemplo.

    {
  "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. Em seguida, está o exemplo de 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.

  • Para garantir que os valores das cadeias não têm erros tipográficos, certifique-se de que executa um programa de verificação de ortografia. 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á completa. 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 os copie e cole. 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.

  • Se utilizar abreviaturas, certifique-se de as colocar as maiúsculas para não haver dúvidas. Isto reduzes a possibilidade de ser confundido com um erro tipográfico.

  • Cadeias no formato CaMel (por exemplo, minimizeHighways ou MinimizeHighways) são normalmente consideradas como não traduzíveis. Se quiser localizar o valor da cadeia, deve fixar a cadeia do formulário CaMel.

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

O Verificador de Soluções é um mecanismo para conduzir análises estáticas de forma a garantir que o conector está a aderir às normas obrigatórias da Microsoft para certificação. Adicione o conector a uma solução no Power Automate ou no Power Apps e execute o verificador de soluções seguindo as instruções apresentadas em Validar um conector personalizado com o verificador de soluções.

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

Passo 4: Adicionar metadados

Os seus artefatos de conector (ficheiros) devem conter metadados específicos a descrever o conector e o serviço final. As informações fornecidas nos metadados são publicadas na documentação do conector e podem ser acedidas publicamente por todos os utilizadores. Não forneça quaisquer informações privadas ou confidenciais e informe-nos através do seu contacto da Microsoft se existirem quaisquer problemas em fornecer-nos estas informações. Para aprender como os metadados são documentados, visite qualquer uma das páginas de documentação específicas do conector em Referência de conector.

Passo 4a: propriedades de editor e stackOwner

  • "editor" é o nome da sua empresa ou organização. Forneça o nome completo da empresa (por exemplo, "Contoso Corporation"). Isto tem de estar no formato alfanumérico.
  • "StackOwner" é a empresa ou organização proprietária da pilha de serviço de back-end a que o conector está a ligar. Isto tem de estar no formato alfanumérico.
Editor Descrição Exemplo
Verificado O editor e o stackOwner são os mesmos, a menos que o ISV esteja a criar um conector em nome de um stackOwner. "editor": "Tesla",
"stackOwner": "Tesla"
Independente Tem de fornecer o proprietário da pilha e o proprietário do editor. "editor": "Nirmal Kumar",
"stackOwner": "ITGlue"

Localização do arquivo: openapidefinition.json

Sintaxe: As propriedades publisher e stackOwner existem como propriedades de nível superior dentro do arquivo openapidefinition.json. Adicione as seguintes linhas destacadas como mostrado. Certifique-se de que introduz o nome da propriedade e o esquema exatamente como mostrado.

Captura de ecrã que mostra as propriedades publisher e stackOwner, que estão disponíveis em Fragmentos de código de exemplo.

Passo 4c: Fragmentos de código de exemplo

Pode utilizar os seguintes fragmentos de código para copiar e introduzir as suas informações. Certifique-se de que adiciona os fragmentos aos ficheiros corretos nas localizações corretas, conforme descrito na secção anterior.

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

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

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

Nota

Existe uma limitação atual na utilização da propriedade stackOwner e da ferramenta de CLI Paconn. Saiba mais em Limitações no arquivo LEIA-ME.

Passo 4d: formatação e limitações do ficheiro JSON

  • Certifique-se de que as propriedades estão corretamente alinhadas.

  • Cole o seu JSON no Visual Studio Code. Pode utilizar extensões, tais como verificações de ortografia e plug-ins, tais como plug-ins JSON.

  • Os ficheiros Swagger devem ser superiores a 1 MB.

    • Pense na estrutura do seu conector antes de o começar a criar. Avalie se o conector deve ser dividido em dois (2) ou mais conectores.
    • A utilização de ficheiros swagger maiores poderá causar um atraso na utilização do conector.

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

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

Passo 5: Cumprir os requisitos de submissão para plug-ins

Esta secção aplica-se, também, se estiver a submeter o plug-in do conector associado para certificação.

Passo 6: Preparar os artefactos do conector e/ou do plug-in

Nota

  • Certifique-se de que seguiu as especificações e garantiu a qualidade do seu conector e/ou plugin antes da certificação. Caso contrário, ocorrerão atrasos na certificação, uma vez que terá de fazer alterações.
  • Forneça uma versão de produção do URL do sistema anfitrião. Não são permitidos URLs de preparação, desenvolvimento e de sistema de anfitrião de teste.

Você está enviando para a Microsoft um conjunto de arquivos, que é uma geração de solução do portal maker ou Microsoft Copilot Studio. Para empacotar seus arquivos, siga as etapas nesta secção.

Guia de empacotamento de conectores e plug-ins

Os procedimentos nesta secção orientam o utilizador por vários cenários de empacotamento. Se você quiser empacotar apenas um conector personalizado, use o primeiro cenário. Se você quiser empacotar um conector personalizado e plugins, use o segundo cenário. Se você quiser empacotar um conector e plug-ins existentes, use o último cenário.

Empacotar o seu conector personalizado e submetê-lo para certificação

  1. Criar um conector personalizados para uma solução.

  2. Executar o verificador de soluções na sua solução de conector no passo 1.

  3. Exportar a solução de conector.

  4. Criar um fluxo (teste) utilizando o conector personalizado recém-criado e adicionar o fluxo a uma solução.

  5. Exportar a solução do fluxo.

  6. Criar um pacote com as soluções dos passos 3 e 5.

  7. Criar um ficheiro intro.md.

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

    Captura de ecrã das pastas e ficheiros num ficheiro zip para que um conector certificado seja certificado.

Nota

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

  1. Carregar o pacote para um blob de armazenamento e gerar o URL da SAS. Verifique se o URI do SAS é válido por pelo menos 15 dias.
  2. Submeter o seu pacote no Centro de Parceiros.

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

  1. Siga os passos 1 a 5 em Empacotar o seu conector personalizado e submeter para certificação neste artigo.

  2. Criar um plug-in no portal do Microsoft Copilot Studio e exportá-lo como uma solução.

  3. Criar um pacote a partir do seguinte:

  4. Criar um ficheiro intro.md.

  5. Criar o pacote final como um ficheiro zip, que está no seguinte formato.

    Captura de ecrã das pastas e ficheiros num ficheiro zip para que um conector e/ou plug-in certificado seja certificado.

Nota

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

  1. Carregar o pacote para um blob de armazenamento e gerar o URL da SAS. Verifique se o URI do SAS é válido por pelo menos 15 dias.
  2. Submeter o seu pacote no Centro de Parceiros.

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

  1. Criar uma solução no Power Automate e adicionar o conector já certificado.

  2. Siga os passos 2 a 4 em Empacotar o seu conector personalizado e submeter para certificação neste artigo.

  3. Criar um plug-in no Copilot Studio e exportá-lo como uma solução.

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

  5. Criar um pacote a partir do seguinte:

  6. Criar um ficheiro intro.md.

  7. Criar o pacote final como um ficheiro zip, que está no seguinte formato.

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

Nota

The names of the folder and files outside the solution are only for reference—you can choose as per your requirements. However, don't manipulate the files inside the solution.

  1. Carregar o pacote para um blob de armazenamento e gerar o URL da SAS. Verifique se o URI do SAS é válido por pelo menos 15 dias.
  2. Submeter o seu pacote no Centro de Parceiros.

Tanto editores verificados quanto editores independentes baixam openapidefinition.json em seus artefatos. Vai precisar de configurar o IconBrandColor neste ficheiro.

  • Editores verificados: defina iconBrandColor para a cor da sua marca no arquivo openapidefinition.
  • Editores independentes: defina iconBrandColor como "#da3b01" no arquivo openapidefinition.
    Screenshot de um ícone laranja vívido (da3b01).

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 um exemplo de documentação a incluir, vá ao exemplo de Leia-me.md. Para saber mais sobre como escrever um ficheiro intro.md, veja outros ficheiros intro.md (também conhecidos como ficheiros Readme.md) no nosso repositório do GitHub.

Se for um editor independente e o seu conector utilizar o OAuth, certifique-se de que inclui instruções sobre como obter credenciais.

Dica

Problemas e Limitações Conhecidos é uma secção excelente para manter os seus utilizadores atualizados.

Passo 7: Validar o pacote para a estrutura

O script de validação do pacote valida a estrutura do pacote e ajuda a gerar o pacote no formato aceitável para certificação. Baixe o script do validador de pacotes com este link: ConnectorPackageValidator.ps1.

Para executar o script, siga estes passos:

  1. Abra o Windows PowerShell no modo Admin.

    Captura de ecrã do Windows PowerShell no modo Admin.

  2. Altere o local da unidade digitando cd /.

    O exemplo a seguir usa C:\.

    Captura de ecrã da sintaxe para alterar a unidade.

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

    Captura de tela da sintaxe para alterar o caminho.

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

    Set-ExecutionPolicy -ExecutionPolicy Unrestricted

    Captura de tela da sintaxe para definir a política de execução.

    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 ConnectorPackageValidator.ps1 com as seguintes etapas:

    1. Insira o caminho do arquivo zip que contém o pacote do conector.
    2. Especifique se o plug-in de IA está habilitado ou não.

    Como mostrado no exemplo a seguir, o primeiro argumento é um caminho de arquivo zip válido que contém o pacote. O segundo argumento é yes/y indicar que o plug-in de IA está habilitado ou no/n indicar que está desativado.

    Captura de tela da sintaxe para executar ConnectorPackageValidator.ps1.

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

    Captura de ecrã da mensagem de sucesso.

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

    Captura de ecrã dos detalhes do problema.

Passo 8: Enviar o seu conector e/ou plug-in para certificação

Durante o processo de submissão, estará a colocar o seu conector e/ou plug-in em open source no nosso repositório de Conectores do Microsoft Power Platform.

  1. (Para editores independentes) Para submeter o pacote à Microsoft para certificação, siga as instruções no Processo de Certificação de Editor Independente.

  2. (Para editores verificados) Para submeter o pacote à Microsoft para certificação no Centro de Parceiros, siga as instruções no Processo de Certificação de 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 o ID de Cliente e o Segredo no Centro de Parceiros. 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 precisar de resolver erros de swagger, vá para Corrigir erros do Validador do Swagger.

Lista de verificação antes de submeter

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

Dica

  • Crie vídeos no YouTube, blogues ou outros conteúdos para partilhar exemplos ou capturas de ecrã sobre como começar a trabalhar com o conector e/ou plug-in.
  • Inclua as ligações no ficheiro intro.md, para que possamos adicionar aos nossos documentos.
  • Adicione dicas ao seu ficheiro swagger para ajudar os seus utilizadores a ter mais êxito.

Próximo passo