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 sapere come vengono mostrati all'interno del prodotto, vai a Guida per la stringa del connettore.

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

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"

Percorso del file: apiProperties.json
Per altre informazioni, vai al file delle proprietà API.

Sintassi: le proprietà publisher e stackOwner esistono come proprietà di livello superiore all'interno del file apiProperties.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 maggiori informazioni, vedi la sezione relativa alle limitazioni nel file LEGGIMI.

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 connettori HubSpot.

Passaggio 4e: convalidare i file del connettore personalizzato

Eseguire paconn validate --api-def [Location of apiDefinition.swagger.json]. Questo strumento convalida la definizione del connettore e permetterà di scoprire eventuali errori da correggere prima dell'invio.

Se il connettore usa OAuth come tipo di autenticazione, aggiungere nell'app questi URL di reindirizzamento inclusi nell'elenco di indirizzo consentiti:

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

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

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.

A Microsoft invii un set di file scaricati tramite uno strumento dell'interfaccia della riga di comando (CLI) fornito da Microsoft. Questo strumento convalida il connettore a fronte di eventuali errori che causano un'interruzione.

Per iniziare, segui questa procedura:

  1. Installare lo strumento CLI per i connettori Microsoft Power Platform attenendosi alle istruzioni di installazione.

  2. Accedere a Microsoft Power Platform usando la riga di comando mediante paconn login. Seguire le istruzioni per eseguire l'accesso usando il processo del codice del dispositivo di Microsoft.

  3. Dopo essersi autenticati, scaricare i file del connettore personalizzato:

    • Eseguire paconn download. Selezionare l'ambiente in cui si trova il connettore personalizzato specificando il relativo numero nella riga di comando, quindi selezionare il nome del connettore personalizzato.

    Lo strumento scarica gli artefatti del connettore e/o del plug-in in una cartella nella posizione del file system in cui è stato eseguito paconn. A seconda del tipo di editore, troverai vari artefatti:

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. Utilizza il primo scenario se desideri creare un pacchetto solo per un connettore personalizzato. Utilizza il secondo scenario se desideri creare un pacchetto per un connettore e un plug-in personalizzati. Utilizza l'ultimo scenario se desideri creare un pacchetto per un connettore e un plug-in esistenti.

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.

  9. Carica il pacchetto in un BLOB di archiviazione e genera l'URL SAS.

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

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 e un plug-in certificati esistenti da certificare.

Sia gli editori verificati che gli editori indipendenti scaricano apiProperties.json nei loro elementi. È necessario impostare IconBrandColor in questo file.

  • Editori verificati: imposta iconBrandColor sul colore del tuo marchio nel file apiProperties.
  • Editori indipendenti: imposta iconBrandColor su "#da3b01" nel file apiProperties.
    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: 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