Condividi tramite

Preparare il connettore e i file dei connettori abilitati per l'IA per la certificazione

Dopo aver completato lo sviluppo del connettore Microsoft Copilot Studio e Microsoft Power Platform personalizzato o i file dei connettori abilitati per l'intelligenza artificiale per la certificazione. Come editore indipendente o verificato, attieniti alla seguente procedura per prepararlo per la certificazione e generare i file del connettore abilitato per l'IA o del connettore da inviare a Microsoft.

Nota

Questo articolo fornisce informazioni per la certificazione dei connettori personalizzati in App per la logica di Azure, Microsoft Power Automate, Microsoft Power Apps e i file dei connettori abilitati per l'intelligenza artificiale per Microsoft Copilot Studio. Prima di seguire i passaggi in questo articolo, leggi Certificazione del connettore e/o dell'azione (plug-in).

Passaggio 1: soddisfare i requisiti di invio per i connettori

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

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, Connettore, Copilot Studio o uno qualsiasi dei quattro nomi di prodotto 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 di connettori e/o azioni corretti: Azure Sentinel*, *Office 365 Outlook
  • Titoli di connettori e/o azioni non corretti: Azure Sentinel's Power Apps Connector, Office 365 Outlook API

Scrivere una descrizione per il connettore

La descrizione deve soddisfare i seguenti requisiti:

  • Assicurati che la descrizione sia conforme alle linee guida del marketplace.
  • 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.
  • Deve essere più lungo di 30 caratteri o più corto di 500 caratteri.
  • Non può contenere Copilot Studio o altri nomi di prodotto 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 in un intervallo compreso 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 Copilot Studio o altri nomi di prodotto 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:

  • Verifica che openapidefinition.json sia un file JSON del formato corretto.
  • 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:

  • Assicurarsi che la proprietà sia aggiornata con i 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 ha Generico OAuth come autenticazione, 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 un esempio di provider di identità OAuth2 GitHub:

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

  • 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 copiare e incollare i riepiloghi. 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.

  • Assicurati di mettere in maiuscolo le abbreviazioni per renderle chiare. Ciò riduce la possibilità che vengano scambiate per un errore tipografico.

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

Passaggio 2: esegui Verifica soluzione per convalidare il connettore

Verifica soluzione è un meccanismo per condurre un'analisi statica per garantire che il connettore aderisca agli standard di certificazione Microsoft. Aggiungi il connettore a una soluzione in Power Automate o Power Apps e quindi segui le istruzioni in Convalidare un connettore personalizzato con Verifica soluzione per eseguire Verifica soluzione.

Guarda questo video per imparare come eseguire Verifica soluzione.

Passaggio 3: Soddisfare i requisiti di invio per le azioni del connettore

Se stai inviando anche le azioni del connettore associate per la certificazione, assicurati di seguire tutte le linee guida in questi articoli:

Passaggio 4: Preparare il connettore, il connettore abilitato per l'intelligenza artificiale e/o gli artefatti

Nota

  • Segui tutte le specifiche per verificare la qualità del connettore e/o del connettore abilitato per l'IA 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 un set di file a Microsoft, che è una generazione di soluzioni dal Maker Portal o da Microsoft Copilot Studio. Per creare un pacchetto di file, segui i passaggi descritti in questa sezione.

Guida alla confezione di connettori e connettori abilitati all'IA

Le procedure presenti in questa sezione ti guidano attraverso vari scenari di creazione di pacchetti. Se desideri creare il pacchetto solo di un connettore personalizzato, usa il primo scenario. Se desideri creare un pacchetto da un connettore personalizzato e da un connettore abilitato per l'IA, usa il secondo scenario. Se desideri creare un pacchetto da un connettore esistente e da un connettore abilitato per l'IA, usa lo scenario più recente.

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

  1. Creare un connettore personalizzato in 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 di test usando il connettore personalizzato appena creato oppure aggiungi un flusso esistente nella 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 nel seguente formato:

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

Nota

I nomi delle cartelle e dei file esterni alla soluzione servono solo come riferimento. Puoi sceglierli in base alle tue esigenze. Invece, non manipolare i file all'interno della soluzione.

  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.

Preparare il connettore personalizzato e il connettore abilitato per l'IA 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

I nomi delle cartelle e dei file esterni alla soluzione servono solo come riferimento. Puoi sceglierli in base alle tue esigenze. Invece, non manipolare i file all'interno della soluzione.

  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.

Preparare il connettore certificato esistente e il connettore abilitato per l'IA per la certificazione

  1. Crea una soluzione in Power Automate e aggiungi il connettore già certificato ad essa.

  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. Estendere gli agenti Microsoft 365 Copilot o Copilot con azioni del connettore.

  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.

Nota

I nomi delle cartelle e dei file esterni alla soluzione servono solo come riferimento. Puoi sceglierli in base alle tue esigenze. Invece, non manipolare i file all'interno della soluzione.

  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 gli editori indipendenti scaricano openapidefinition.json nei loro elementi. È necessario impostare IconBrandColor in questo file.

  • Editori verificati: imposta iconBrandColor sul colore del tuo marchio nel file openapidefinition.
  • Editori indipendenti: imposta 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 5: convalidare la struttura del pacchetto

Lo script di convalida del pacchetto convalida la struttura del pacchetto e consente di generare il pacchetto in un formato accettabile per la certificazione. Scaricare lo script di convalida del pacchetto con questo collegamento: ConnectorPackageValidator.ps1.

Per eseguire lo script, esegui questi passaggi:

  1. Apri Windows PowerShell in modalità amministratore.

    Screenshot di Windows PowerShell in modalità amministratore.

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

    Il seguente esempio usa C:\.

    Screenshot della sintassi per modificare l'unità.

  3. Passare al percorso in cui è stato scaricato lo script di convalida del pacchetto.

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

    Screenshot della sintassi per modificare il percorso.

  4. Imposta i criteri di esecuzione su senza restrizioni immettendo il seguente comando:

    Set-ExecutionPolicy -ExecutionPolicy Unrestricted

    Screenshot della sintassi per impostare i criteri di esecuzione.

    Questo comando consente di eseguire il PowerShell senza alcuna restrizione.

  5. Conferma l'immissione immettendo Y, che indica Sì.

  6. Esegui ConnectorPackageValidator.ps1 con i passaggi seguenti:

    1. Immetti il percorso del file ZIP che contiene il pacchetto del connettore.
    2. Specifica se l'azione di intelligenza artificiale è abilitata o meno.

    Come illustrato nell'esempio seguente, il primo argomento è un percorso di file ZIP valido che contiene il pacchetto. Il secondo argomento è yes/y ad indicare che l'azione IA è abilitato o no/n ad indicare che è disabilitato.

    Mostra la sintassi per eseguire ConnectorPackageValidator.ps1.

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

    Evidenzia il messaggio di esito positivo, Convalida riuscita: la struttura del pacchetto è corretta.

    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.

    Evidenzia il messaggio dei dettagli del problema, Convalida non riuscita: struttura del pacchetto non valida. Controlla i messaggi precedenti per i dettagli.

Passaggio 6: inviare il connettore e/o il connettore abilitato all'intelligenza artificiale per la certificazione

Durante il processo di invio, si distribuirà come open source il connettore e/o il connettore abilitato all'IA 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 ha OAuth, fornisci l'ID client e il 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:

Per domande relative alla certificazione

Devi avere Microsoft Teams per partecipare alla riunione Orario di ufficio. Se hai bisogno di accedere, visualizza le opzioni in Microsoft Teams.

Partecipa alla Riunione Orario d'ufficio ogni martedì dalle 15:30 alle 16:30 UTC (Coordinated Universal Time).

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