Processo de certificação de editores verificados

  • Artigo

Este processo é para editores verificados (excluindo editores independentes). Se for um editor independente, aceda ao Processo de certificação de editores independentes.

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

Nota

Este tópico fornece informações para a certificação de conectores personalizados no Azure Logic Apps, Power Automate e Power Apps. Antes de seguir os passos neste artigo, leia Certifique o seu conector e registe o seu conector personalizado com a Microsoft.

Fluxo de trabalho básico do processo de certificação

O fluxograma que se segue mostra o fluxo de trabalho básico do processo de certificação. Os passos numerados neste artigo correspondem ao fluxo de trabalho. Devem fornecer os detalhes necessários para completar o processo de certificação.

Para uma vista expandida do fluxograma, selecione o ícone de lupa no canto inferior direito.

Fluxo de trabalho do processo de certificação do conector.

Para uma vista aprofundada deste fluxograma, aceda ao Fluxo de trabalho do processo de certificação do conector aprofundado.

Passo 1: Registar o conector personalizado

Não tem de concluir o desenvolvimento do conector personalizado para solicitar a certificação. Para iniciar o processo de certificação, registe o seu conector 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 irá:

  • Compreender o conector personalizado.
  • Saber mais sobre o progresso do seu desenvolvimento.
  • Guiá-lo através do processo de certificação.

Passo 2: Cumprir os requisitos de submissão

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

  • Tem de existir e ser escrito em inglês.
  • Tem de ser exclusivo e distinto de qualquer título de conector existente.
  • Deve ter o nome do seu produto ou organização.
  • Deve seguir os padrões de nomeação existentes para conectores certificados. Para editores independentes, o nome do conector deve seguir o padrão, Nome do conector (Editor independente).
  • Não pode ter mais de 30 carateres.
  • Não pode conter as palavras "API", "Connector" ou qualquer um 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

  • Títulos de conectores corretos: "Azure Sentinel", "Office 365 Outlook"
  • Títulos de conectores corretos: "Azure Sentinel's Power Apps Connector", "Office 365 Outlook API"

Escreva uma descrição para o seu conector

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

Crie um ícone para o conector

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).
  • Tem de conter um fundo não transparente, cor não branca (#ffffff) e cor não predefinida (#007ee5) que corresponda à cor de fundo do ícone especificado.
  • Tem de ser exclusivo de qualquer outro ícone de conector certificado.
  • Tem de ser submetido em formato PNG como "icon.png".
  • As dimensões do logótipo estão abaixo de 70% para a altura e largura da imagem com 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

  • 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

  • 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

  • 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

  • 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 está a desenvolver 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.

  • Certifique-se de que execute um programa de verificação ortográfica para garantir que os valores das cadeias não têm 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á 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 sobre como são apresentados no produto, aceda a Orientações sobre a cadeia de conectores.

  • 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 na forma CaMel (ex. 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 aprender a 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 ficheiro: apiProperties.json
Para saber mais, aceda a Ficheiro de propriedades API.

Sintaxe: as propriedades publisher e stackOwner existem como propriedades de nível superior no ficheiro apiProperties.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. Para mais informações, aceda a Limitações no ficheiro 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 pode causar um atraso na utilização do conector.

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

    Captura de ecrã de pastas para os três conectores HubSpot.

Passo 4e: validação do seus ficheiros de conector personalizado

Execute o paconn validate --api-def [Location of apiDefinition.swagger.json]. Esta ferramenta valida a definição do conector e indica os erros que tem de corrigir antes da submissão.

Se o seu conector utilizar o tipo de autenticação OAuth, adicione estes URLs de redirecionamento permitidos à sua aplicação:

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

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

Passo 5: Preparar os artefactos do conector

Este passo deve levar cerca de uma semana para completar.

Nota

  • Certifique-se de que seguiu as especificações e garantiu a qualidade do conector 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.

Está a submeter à Microsoft um conjunto de ficheiros chamados artefactos do conector, transferidos através de uma ferramenta de interface de linha de comandos (CLI) fornecida pela Microsoft. Esta ferramenta valida o seu conector por eventuais erros de quebra.

Siga estes passos para começar:

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

  2. Inicie sessão no Microsoft Power Platform através da linha de comandos ao executar paconn login. Siga as instruções para iniciar sessão através do processo Código de Dispositivo da Microsoft.

  3. Depois de ser autenticado, descarregue os seus ficheiros de conector personalizados:

    • Execute o paconn download. Selecione o ambiente onde o conector personalizado está localizado por especificar o respetivo número na linha de comandos e, em seguida, selecione o nome do conector personalizado.

    A ferramenta transfere os artefactos do conector de uma pasta para a localização do sistema onde executou o paconn. Dependendo do tipo de editor, encontra vários artefactos:

Editor Artefacto
Verificado apiDefinition.swagger.json
apiProperties.json
settings.json
O ícone do conector
Independente apiDefinition.swagger.json
apiProperties.json

Tanto os editores verificados como os editores independentes transferem apiProperties.json nos seus artefactos. Vai precisar de configurar o IconBrandColor neste ficheiro.

  • Editores verificados: definir iconBrandColor para a cor da sua marca no ficheiro apiProperties.
  • Editores independetes: definir iconBrandColor para "#da3b01" no ficheiro apiProperties.
    Captura de ecrã de um ícone laranja vívido (da3b01).

Criar um artefacto de ficheiro Leia-me

Um ficheiro Leia-me.md é necessário tanto para editores independentes como para editores verificados. Precisa de criar um ficheiro Leia-me.md para documentar as funcionalidades do seu conector. Para um exemplo de documentação a incluir, aceda a Exemplo readme.md. Veja outros ficheiros Readme.md no nosso Repositório GitHub para saber como escrever um ficheiro Readme.md.

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

Gorjeta

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

Passo 6: Submeter o seu conector para implementação

Durante o processo de submissão, está a colocar o seu conector em open source no nosso repositório de Conectores do Microsoft Power Platform.

  1. Siga as instruções em Submeter o seu conector para certificação Microsoft para submeter para o GitHub e para o portal de certificação.

    Se for um editor verificado, tem de submeter um ficheiro script.csx se estiver a utilizar código personalizado.

  2. Assim que submeter um pedido de puxar para o repositório de open source, a Microsoft implementará e validará o seu conector dentro de 1 a 2 semanas. Se forem necessárias atualizações, permita 1 a 2 semanas adicionais.

    **Se o conector tiver OAuth, envie o pacote no ISV Studio e obtenha o APIname do pedido de envio do conector para atualizar a sua aplicação.

    Como parte da submissão, a Microsoft valida o seu conector ao utilizar as ferramentas CLA-bot, Swagger Validator e Breaking Change Detector. Se precisar de resolver erros de swagger, vá para Corrigir erros do Validador do Swagger.

Passo 7: Expetativas para testes feitos por editores verificados

Depois de validarmos o seu conector, iremos pedir-lhe para realizar testes minuciosos.

  1. Siga as instruções em Testar o seu conector em certificação para criar um ambiente na região de Pré-visualização em preparação para o seu teste.

  2. Dentro de uma semana, notifique o seu contacto da Microsoft de que completou os testes para que possamos começar a implementar.

  3. Depois da funcionalidade e do conteúdo do seu conector serem validados tanto pela Microsoft como por si, iremos preparar o conector para implementação na região Pré-visualização para testes.

Passo 8: Aguardar a implementação

Após o seu conector ser validado para teste, iremos implementá-lo em todos os produtos e regiões.

Importante

Em média, são necessárias 3 a 4 semanas para implementar o conector. Isto é necessário independentemente do tamanho ou complexidade do seu conector, seja novo ou uma atualização. Para proteger a integridade, o conector será submetido às mesmas tarefas de validação para testar a funcionalidade e o conteúdo que são seguidas em todas as implementações.

Vamos notificá-lo por e-mail com os nomes das regiões para onde o conector será implementado, uma vez que a implementação para as regiões é feita em passos. Se houver um atraso de implementação ou congelamento, os editores verificados podem encontrar o estado no Controlo de Atividades no portal ISV. Os editores independentes serão notificados por e-mail.

Implementação de produção

As nossas agendas de implementação de conector para produção começam nas manhãs de sexta-feira, PST/PDT. Tem de informar a Microsoft de que está pronto para a implementação de produção com, pelo menos, 24 horas de antecedência para incluir o seu conector na próxima implementação agendada. Os editores verificados podem notificar-nos no Controlo de Atividades do portal ISV. Os editores independentes podem notificar o seu contacto da Microsoft.

Implementação de região

A implementação em várias regiões ocorre numa sequência diária predeterminada. As regiões são:

  • A testar.
  • Pré-visualização nos EUA.
  • Ásia, exceto o Japão e Índia.
  • Europa, exceto RU.
  • Brasil, Canadá, Japão e Índia.
  • Austrália, RU e EUA.

Por exemplo, se o seu conector estiver agendado para implementação na segunda-feira, faz a implementação da região de Teste no dia 1. Em seguida, implementa na região de pré-visualização nos EUA no Dia 2. A implementação continua diariamente até que o conector seja implementado nas seis regiões.

Não implementamos aos sábados, domingos e feriados dos EUA.

Como o seu conector está a terminar a certificação, vamos envolvê-lo sobre uma oportunidade de marketing para o conector no blogue do Power Automate.

Passo 9: Explorar opções pós-implementação

Eis algumas opções que pode explorar após o seu conector ser implementado:

Lista de verificação antes de submeter

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

Gorjeta

  • 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.
    - Inclua as ligações no ficheiro Readme.md, para que possamos adicionar aos nossos documentos.
  • Adicione dicas ao seu ficheiro swagger para ajudar os seus utilizadores a ter mais êxito.

Se for um editor verificado (e não um editor independente), é-lhe pedido que aceite o nosso Contrato de Parceiro e um acordo de não divulgação quando se submeter a uma certificação Microsoft. Se quiser rever estes termos e a linguagem antes da submissão, contacte o seu contacto da Microsoft.

Próximo passo

Submeter o conector para certificação Microsoft

Enviar comentários

Apreciamos os comentários sobre problemas com a nossa plataforma de conectores ou novas ideias de funcionalidades. Para enviar comentários, aceda a Submeter problemas ou obter ajuda com conectores e selecione o tipo de comentários.