Condividi tramite

Preparare i file di connettori e plug-in di Power Platform per la certificazione

  • Articolo

Questo processo è inteso per gli editori verificati e quelli indipendenti.

Dopo aver completato lo sviluppo del connettore e/o del plug-in personalizzato, segui questi passaggi per prepararlo per la certificazione e generare i file del connettore e/o del plug-in da inviare a Microsoft.

Nota

Questo articolo fornisce informazioni per la certificazione di connettori personalizzati in App per la logica di Azure, Power Automate e Power Apps nonché di plug-in in Copilot. Prima di seguire i passaggi in questo articolo, leggi Ottenere la certificazione di un connettore e/o di un plug-in.

Passaggio 1: registrare il connettore e/o il plug-in (applicabile solo per editori indipendenti)

Questa sezione non si applica agli editori verificati.

Per richiedere la certificazione, non è necessario aver completato lo sviluppo del connettore e/o del plug-in personalizzato. Per iniziare il processo di certificazione, registra il connettore e/o il plug-in per la certificazione compilando il modulo di registrazione.

Aspettati di ricevere un'e-mail entro due giorni lavorativi da un contatto Microsoft che:

  • Comprende il connettore personalizzato, il connettore e/o il plug-in.
  • Si informa sull'avanzamento dello sviluppo.
  • Ti informa del processo di certificazione via e-mail.

Passaggio 2: soddisfare i requisiti di invio per i connettori

Per mantenere un elevato standard di qualità e coerenza tra i nostri connettori certificati, Microsoft ha una serie di requisiti e linee guida che il tuo connettore personalizzato deve rispettare per la certificazione.

Assegnare un titolo al connettore

Il titolo deve soddisfare i seguenti requisiti.

  • Deve esistere ed essere scritto in inglese.
  • Deve essere univoco e distinguibile da altri titoli di connettori e/o plug-in esistenti.
  • Deve essere il nome del prodotto o dell'organizzazione.
  • Deve seguire i modelli di denominazione esistenti per i connettori e/o i plug-in certificati. Per gli editori indipendenti, il nome del connettore deve seguire lo schema Connector and/or plugin Name (Independent Publisher).
  • Non deve superare i 30 caratteri.
  • Non può contenere le parole API, Connector o uno dei nomi di prodotto di Power Platform, ad esempio Power Apps.
  • Non può terminare con un carattere alfanumerico, inclusi ritorno a capo, carattere di nuova riga o spazio vuoto.

Esempi

  • Titoli soddisfacenti per connettori e/o plugin: Azure Sentinel*, *Office 365 Outlook
  • Titoli non soddisfacenti per connettori e/o plugin: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Scrivere una descrizione per il connettore

La descrizione deve soddisfare i seguenti requisiti.

  • Deve esistere ed essere scritto in inglese.
  • Non deve contenere errori grammaticali o di ortografia.
  • Deve descrivere in maniera concisa lo scopo principale e il valore offerto dal connettore.
  • Non può avere una lunghezza inferiore a 30 caratteri o superiore a 500 caratteri.
  • Non può contenere nomi di prodotti Power Platform (ad esempio, 'Power Apps').

Progettare un'icona per il connettore (applicabile solo agli editori verificati)

Questa sezione non si applica agli editori indipendenti.

  • Crea un logo con dimensioni 1:1 comprese tra 100 x 100 e 230 × 230 pixel (senza bordi arrotondati).
  • Usa un colore di sfondo non trasparente e non bianco (#ffffff) e un colore non predefinito (#007ee5) che corrisponda al colore di sfondo dell'icona specificato.
  • Assicurati che l'icona sia unica per qualsiasi altra icona del connettore certificata.
  • Invia il logo in formato PNG come <icon>.png.
  • Imposta le dimensioni del logo al di sotto del 70% per l'altezza e la larghezza dell'immagine con uno sfondo coerente.
  • Assicurati che il colore del marchio sia un colore esadecimale valido e non sia bianco (#ffffff) o predefinito (#007ee5).

Definire riepilogo e descrizione di operazioni e parametri

I riepiloghi e le descrizioni devono soddisfare i seguenti requisiti.

  • Deve esistere ed essere scritto in inglese.
  • Non deve contenere errori grammaticali o di ortografia.
  • I riepiloghi di operazioni e parametri devono essere frasi di 80 caratteri o meno e contenere solo caratteri alfanumerici o parentesi.
  • Le descrizioni di operazioni e parametri deve essere composta da frasi descrittive complete che terminano con un punto.
  • Non può contenere alcun nome di prodotto Microsoft Power Platform (ad esempio, "Power Apps").

Definire risposte esatte per le operazioni

Le risposte per le operazioni devono soddisfare i seguenti requisiti.

  • Definire le risposte per le operazioni con uno schema esatto solo con le risposte previste.
  • Non utilizzare risposte predefinite con una definizione di schema esatta.
  • Fornire definizioni di schema di risposta valide per tutte le operazioni nello swagger.
  • Gli schemi di risposta vuoti non sono consentiti tranne in casi speciali in cui lo schema di risposta è dinamico. Ciò significa che nessun contenuto dinamico verrà mostrato nell'output e i creatori devono utilizzare JSON per analizzare la risposta.
  • Non sono consentite operazioni vuote.
  • Rimuovi le proprietà vuote a meno che non siano obbligatorie.

Verifica le proprietà di swagger

Le proprietà devono soddisfare i seguenti requisiti.

  • Assicurati che "openapidefinition" sia in un file JSON formattato correttamente.
  • Garantire che la definizione di swagger sia conforme allo standard OpenAPI 2.0 e allo standard esteso dei connettori.

Verifica i parametri di connessione

I parametri devono soddisfare i seguenti requisiti.

  • Assicurati che la proprietà sia aggiornata con valori appropriati per "UIDefinition" (nome visualizzato, descrizione).

  • Se il parametro di connessione utilizza l'autenticazione di base, assicurati che JSON sia formattato correttamente come nell'esempio seguente.

    {
  "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 il parametro di connessione utilizza l'autenticazione APIKey, assicurati che JSON sia formattato correttamente come nell'esempio seguente.

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

  • Se il parametro di connessione utilizza l'autenticazione OAuth generico, assicurati che JSON sia formattato correttamente come nell'esempio seguente.

    {
  "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 il parametro di connessione prevede un provider di identità OAuth2, assicurati che il provider di identità sia incluso nell'elenco dei provider OAuth2 supportati. Di seguito è riportato l'esempio del provider di identità GitHub OAuth2:

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

  • Se il parametro di connessione utilizza l'autenticazione Microsoft Entra ID, assicurati che JSON sia formattato correttamente come nell'esempio seguente.

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

Creare stringhe in lingua inglese di qualità

I connettori sono localizzati come parte della localizzazione di Power Automate pertanto, quando sviluppi un connettore, la qualità delle stringhe in lingua inglese è fondamentale per la qualità della traduzione. Ecco alcune aree principali su cui concentrarti mentre crei i valori delle stringhe che fornirai.

  • Assicurati di eseguire un programma di controllo ortografico per assicurarti che tutti i valori di stringa siano privi di errori tipografici. Se è presente una stringa in lingua inglese incompleta, il risultato della traduzione sarà incompleto o non corretto nel contesto.

  • Assicurati che la frase sia in forma completa. Se la frase non è completa, anche questo può generare traduzioni di qualità inferiore.

  • Assicurati che il significato della frase sia chiaro. Se il significato della frase è ambiguo, anche questo può generare traduzioni di qualità inferiore o errate.

  • Assicurati che i riepiloghi, i riepiloghi x-ms e le descrizioni siano grammaticalmente corretti. Non copiarli e incollarli. Per scoprire come vengono visualizzati all'interno del prodotto, vai a Guida alle stringhe dei connettori.

  • Evita le stringhe composite di runtime, se possibile. Usa invece frasi completamente formate. Le stringhe o le frasi concatenate rendono difficile la traduzione o possono causare una traduzione errata.

  • Se usi abbreviazioni, assicurati di metterle in maiuscolo per renderle chiare. Ciò riduce la possibilità che vengano scambiate per un errore tipografico.

  • Le stringhe in formato CaMel (ad esempio, minimizeHighways o MinimizeHighways) sono generalmente considerate non traducibili. Se vuoi localizzare il valore della stringa, dovresti correggere la stringa del modulo CaMel.

Passaggio 3: esegui Verifica soluzione per convalidare il connettore

Verifica soluzione è un meccanismo per condurre analisi statiche per garantire che il connettore aderisca agli standard richiesti da Microsoft per la certificazione. Aggiungi il tuo connettore a una soluzione in Power Automate o Power Apps ed esegui la verifica della soluzione seguendo le istruzioni in Convalida di un connettore personalizzato con la verifica della soluzione.

Guarda questo Video per imparare come eseguire Solution Checker.

Passaggio 4: aggiungere metadati

Gli artefatti del connettore (file) devono contenere metadati specifici che descrivono il connettore e il suo servizio finale. Le informazioni fornite nei metadati saranno pubblicate nella documentazione del connettore e sono accessibili pubblicamente a tutti gli utenti. Non fornire informazioni riservate o private e comunicare a Microsoft tramite il contatto dedicato se vi sono problemi nel fornire queste informazioni. Per sapere come verranno documentati i metadati, visita una qualsiasi delle pagine della documentazione specifica del connettore in Informazioni di riferimento sui connettori.

Passaggio 4a: proprietà publisher e stackOwner

  • "publisher" è il nome della società o dell'organizzazione. Fornisci il nome completo dell'azienda (ad esempio "Contoso Corporation"). Deve essere in formato alfanumerico.
  • "stackOwner" è l'azienda o l'organizzazione proprietaria dello stack di servizi back-end cui si collega il connettore. Deve essere in formato alfanumerico.
Server di pubblicazione Description Esempio
Verificato L'editore e stackOwner saranno gli stessi, a meno che l'ISV non stia creando un connettore per conto di uno stackOwner. "publisher": "Tesla",
"stackOwner": "Tesla"
Indipendente Devi fornire il proprietario dello stack e il proprietario dell'editore. "publisher": "Nirmal Kumar",
"stackOwner": "ITGlue"

Posizione del file: openapidefinition.json

Sintassi: Le proprietà publisher e stackOwner esistono come proprietà di primo livello all'interno del file openapidefinition.json. Aggiungere le righe evidenziate di seguito, come mostrato. Assicurarsi di inserire il nome della proprietà e lo schema esattamente come mostrato.

Screenshot che mostra le proprietà publisher e stackOwner, disponibili nei frammenti di codice di esempio.

Passaggio 4c: frammenti di codice di esempio

È possibile utilizzare i seguenti frammenti di codice per copiare e inserire le informazioni. Assicurarsi di aggiungere i frammenti ai file corretti nelle posizioni corrette come descritto nella sezione precedente.

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

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

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

Nota

Al momento è presente una limitazione all'uso della proprietà stackOwner e dello strumento CLI Paconn. Per ulteriori informazioni, consultare la sezione Limitazioni nel file README.

Passaggio 4d: formattazione e limitazioni del file JSON

  • Assicurati che le proprietà siano allineate correttamente.

  • Incolla il tuo JSON in Visual Studio Code. Puoi utilizzare le estensioni come correttori ortografici e plug-in, ad esempio i plug-in JSON.

  • I file Swagger non devono essere più grandi di 1 MB.

    • Considera la progettazione del connettore prima di iniziare a costruirlo. Valuta se il connettore deve essere suddiviso in due (2) o più connettori.
    • I file swagger più grandi possono causare un ritardo quando si utilizza il connettore.

    Ad esempio, sulla piattaforma sono presenti tre (3) diversi connettori HubSpot.

    Screenshot delle cartelle per i tre HubSpot connettori.

Passaggio 5: soddisfare i requisiti di invio per i plug-in

Questa sezione si applica se stai inviando anche il plug-in del connettore associato per la certificazione.

Passaggio 6: preparare gli artefatti del connettore e/o del plug-in

Nota

  • Assicurati di aver seguito le specifiche e di aver verificato la qualità del connettore e/o del plug-in prima della certificazione. In caso contrario, la certificazione subirà ritardi perché verrà chiesto di apportare modifiche.
  • Fornisci una versione di produzione dell'URL host. Gli URL host di staging, sviluppo e test non sono consentiti.

Stai inviando a Microsoft un set di file, che è una generazione di soluzioni dal portale del produttore o Microsoft Copilot Studio. Per impacchettare i file, seguire segui i passaggi descritti in questa sezione.

Guida alla creazione di un pacchetto per connettori e plugin

Le procedure presenti in questa sezione ti guidano attraverso vari scenari di creazione di pacchetti. Se si desidera confezionare solo un connettore personalizzato, utilizzare il primo scenario. Se si desidera creare un pacchetto sia con un connettore personalizzato che con dei plugin, utilizzare il secondo scenario. Se si desidera creare un pacchetto con un connettore e dei plugin esistenti, utilizzare l'ultimo scenario.

Creare un pacchetto per un connettore personalizzato e inviarlo per la certificazione

  1. Crea un connettore personalizzato per una soluzione.

  2. Esegui la verifica della soluzione nella soluzione del connettore nel passaggio 1.

  3. Esporta la soluzione del connettore.

  4. Crea un flusso (test) utilizzando il connettore personalizzato appena creato e aggiungi il flusso a una soluzione.

  5. Esporta la soluzione del flusso.

  6. Crea un pacchetto con le soluzioni dei passaggi 3 e 5.

  7. Crea un file intro.md.

  8. Crea il pacchetto finale come file zip, ovvero nel seguente formato:

    Screenshot delle cartelle e dei file in un file zip per un connettore certificato da certificare.

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. Carica il pacchetto in un BLOB di archiviazione e genera l'URL SAS. Assicurati che il tuo SAS URI sia valido per almeno 15 giorni.
  2. Invia il pacchetto al Centro per i partner.

Creare un pacchetto per un connettore e un plug-in personalizzati per la certificazione

  1. Segui i passaggi da 1 a 5 in Creare un pacchetto per un connettore personalizzato e inviarlo per la certificazione in questo articolo.

  2. Crea un plugin nel portale Microsoft Copilot Studio ed esportalo come soluzione.

  3. Crea un pacchetto come segue:

  4. Crea un file intro.md.

  5. Crea il pacchetto finale come file zip, ovvero nel formato seguente.

    Screenshot delle cartelle e dei file in un file zip per un connettore e un plug-in certificati da certificare.

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. Carica il pacchetto in un BLOB di archiviazione e genera l'URL SAS. Assicurati che il tuo SAS URI sia valido per almeno 15 giorni.
  2. Invia il pacchetto al Centro per i partner.

Creare un pacchetto per un connettore e un plug-in certificati esistenti per la certificazione

  1. Crea una soluzione in Power Automate e aggiungici il connettore già certificato.

  2. Segui i passaggi da 2 a 4 in Creare un pacchetto per un connettore personalizzato e inviarlo per la certificazione in questo articolo.

  3. Crea un plugin in Copilot Studio ed esportalo come soluzione.

  4. Esporta il plug-in come soluzione.

  5. Crea un pacchetto come segue:

  6. Crea un file intro.md.

  7. Crea il pacchetto finale come file zip, ovvero nel formato seguente.

    Screenshot delle cartelle e dei file in un file zip per un connettore certificato esistente e un plugin da certificare.

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. Carica il pacchetto in un BLOB di archiviazione e genera l'URL SAS. Assicurati che il tuo SAS URI sia valido per almeno 15 giorni.
  2. Invia il pacchetto al Centro per i partner.

Sia gli editori verificati che quelli indipendenti scaricano openapidefinition.json i loro artefatti. È necessario impostare IconBrandColor in questo file.

  • Editori verificati: imposta iconBrandColor sul colore del tuo marchio nel file openapidefinition.
  • Editori indipendenti: impostare iconBrandColor su "#da3b01" nel file openapidefinition.
    Screenshot di un'icona arancione brillante (da3b01).

Creare un artefatto intro.md.

Un file intro.md è necessario sia per gli editori indipendenti che per gli editori verificati. Devi creare un file intro.md per documentare le caratteristiche e le funzionalità del connettore. Per un esempio di documentazione da includere, vedi Esempio di gile Leggimi.md. Per informazioni su come scrivere un file intro.md, guarda gli altri file intro.md (noti anche come file Leggimi.md) nel nostro repository GitHub.

Se sei un editore indipendente e il tuo connettore utilizza OAuth, assicurati di includere le istruzioni su come ottenere le credenziali.

Suggerimento

Problemi noti e limitazioni è un'ottima sezione per mantenere aggiornati i tuoi utenti.

Passaggio 7: Convalida il pacchetto per la struttura

Lo script di convalida del pacchetto convalida la struttura del pacchetto e aiuta a generare il pacchetto in un formato accettabile per la certificazione. Scarica lo script di convalida del pacchetto tramite questo link: ConnectorPackageValidator.ps1.

Per eseguire lo script, seguire questi passaggi:

  1. Aprire Windows PowerShell in modalità amministratore.

    Screenshot di Windows PowerShell in modalità amministratore.

  2. Cambiare la posizione dell'unità immettendo cd /.

    Nell'esempio seguente viene utilizzato C:\.

    Screenshot della sintassi per cambiare unità.

  3. Vai al percorso in cui hai scaricato lo script di convalida del pacchetto.

    Ad esempio, se il percorso è C:\Users\user01\Downloads, immettere cd .\Users\user01\Downloads\.

    Screenshot della sintassi per modificare il percorso.

  4. Impostare la policy di esecuzione su senza restrizioni immettendo il seguente comando:

    Set-ExecutionPolicy -ExecutionPolicy Unrestricted

    Screenshot della sintassi per impostare la politica di esecuzione.

    Questo comando consente l'esecuzione di PowerShell senza alcuna restrizione.

  5. Conferma la tua iscrizione digitando Y, che significa Sì.

  6. Eseguire ConnectorPackageValidator.ps1 con i seguenti passaggi:

    1. Immettere il percorso del file zip che contiene il pacchetto del connettore.
    2. Specifica se plug-in IA è abilitato o meno.

    Come mostrato nell'esempio seguente, il primo argomento è un percorso di file zip valido che contiene il pacchetto. Il secondo argomento serve a indicare che plug-in IA è abilitato oppure che è disabilitato. yes/y no/n

    Screenshot della sintassi per eseguire ConnectorPackageValidator.ps1.

    Se la struttura del pacchetto è corretta, viene visualizzato il seguente messaggio di successo:

    Screenshot del messaggio di successo.

    Se si verifica un problema con la struttura del pacchetto, lo script fornisce i dettagli del problema rilevando ed evidenziando i difetti nella struttura del pacchetto.

    Screenshot dei dettagli del problema.

Passaggio 8: inviare il connettore e/o il plug-in per la certificazione

Durante il processo di invio, distribuisci come open source il connettore e/o il plug-in al nostro Repository dei connettori Microsoft Power Platform.

  1. (Per editori indipendenti) Per inviare il pacchetto a Microsoft per la certificazione, segui le istruzioni in Processo di certificazione per editori indipendenti.

  2. (Per editori verificati) Per inviare il pacchetto a Microsoft per la certificazione nel Centro per i partner, segui le istruzioni in Processo di certificazione per editori verificati.

    Se sei un editore verificato, dovrai inviare un file script.csx se utilizzi un codice personalizzato.

    Se il tuo connettore dispone di OAuth, fornisci l'ID client e segreto nel Centro per i partner. Inoltre, ottieni il nome API dalla richiesta di invio del connettore per aggiornare la tua app.

    Nell'ambito dell'invio, Microsoft certifica il connettore e/o il plug-in. Se hai bisogno di risolvere gli errori relativi allo swagger, vedi Correggere gli errori di convalida Swagger.

Elenco di controllo prima dell'invio

Prima di passare a Inviare il connettore per la certificazione Microsoft, assicurarsi di quanto segue:

Suggerimento

  • Crea video YouTube, blog o altri contenuti per condividere esempi o screenshot su come iniziare a utilizzare il connettore e/o il plug-in.
  • Includi i collegamenti nel file intro.md in modo che possiamo aggiungerlo alla nostra documentazione.
  • Aggiungi le descrizioni comando al tuo file swagger per aiutare i tuoi utenti a essere più efficaci.

Passaggio successivo