Introduzione
I connettori personalizzati consentono di implementare un connettore per i servizi che non sono disponibili nei connettori predefiniti di Microsoft Power Platform. Gli sviluppatori possono usare codice personalizzato per implementare la trasformazione avanzata dell'input e dell'output delle azioni di un connettore.
La definizione di un connettore personalizzato di base stabilisce i trigger e le azioni disponibili agli autori che lo usano. Quando un autore usa l'azione da un'app o da un flusso, l'operazione dell'API viene richiamata passando il payload di richiesta impostato nella definizione del connettore personalizzato. Il payload di risposta del servizio deve corrispondere alla definizione della risposta dell'azione del connettore personalizzato. Non si verificano trasformazioni nel payload di richiesta e di risposta.
Modelli di criteri
Le definizioni delle azioni del connettore possono implementare una trasformazione di base senza codice della richiesta e della risposta al servizio, applicando modelli di criteri del connettore personalizzato. Ad esempio, i modelli di criteri possono eseguire i seguenti tipi di trasformazioni:
Conversione di dati di richiesta o risposta da un oggetto a una matrice.
Conversione di dati di richiesta o risposta da una matrice a un oggetto.
Impostazione dell'URL dell'host della richiesta.
Impostazione dei valori di intestazione HTTP della richiesta.
Impostazione del valore di una proprietà nella richiesta o nella risposta.
Impostazione dei parametri di stringa della query di richiesta.
È possibile usare più modelli di criteri insieme per trasformare la richiesta e la risposta. Quando si impostano più modelli, si deve modificare anche l'ordine per controllare la sequenza dell'applicazione dei criteri.
Gli sviluppatori possono implementare codice personalizzato per andare oltre le capacità dei modelli di criteri. Infatti, quando si implementa il codice personalizzato, la logica assume il controllo completo sulla trasformazione della richiesta e della risposta, inclusa l'attività di richiamo dell'operazione sul servizio sottostante.
Implementazione di codice personalizzato
Per implementare il codice personalizzato, è necessario creare una classe denominata Script che deve ereditare dalla classe base astratta ScriptBase. La classe ScriptBase definisce un metodo astratto, ExecuteAsync, da implementare nella classe Script per implementare correttamente il codice personalizzato in un connettore. Il metodo ExecuteAsync dovrebbe essere l'implementazione completa di qualsiasi trasformazione e invocazione del servizio sottostante.
L'esempio seguente mostra una classe che implementa gli elementi richiesti:
public class Script : ScriptBase
{
public override Task<HttpResponseMessage> ExecuteAsync()
{
// Your code here
}
}
Il metodo ExecuteAsync deve fornire l'implementazione completa di qualsiasi trasformazione e invocazione del servizio sottostante. Nell'esempio seguente, il servizio sottostante non viene richiamato e ogni risposta è un oggetto contenente una proprietà greeting impostata su "Hello World!".
public override async Task<HttpResponseMessage> ExecuteAsync()
{
// Create a new response
var response = new HttpResponseMessage();
// Set the content
// Initialize a new JObject and call .ToString() to get the serialized JSON
response.Content = CreateJsonContent(new JObject
{
["greeting"] = "Hello World!",
}.ToString());
return response;
}
Per richiamare il servizio sottostante si deve usare il metodo SendAsync sull'oggetto context. Il seguente metodo ExecAsync non esegue alcuna trasformazione, ma inoltra la richiesta al servizio sottostante e quindi restituisce la risposta inalterata.
public override async Task<HttpResponseMessage> ExecuteAsync()
{
HttpResponseMessage response = await this.Context.SendAsync(this.Context.Request, this.CancellationToken).ConfigureAwait(continueOnCapturedContext: false);
return response;
}
L'uso più comune del codice personalizzato consiste nel fornire la trasformazione della richiesta prima della chiamata al metodo SendAsync. In alternativa, è possibile trasformare la risposta del metodo SendAsync prima della restituzione dal metodo ExecuteAsync.
Creazione di codice personalizzato per le operazioni
È possibile abilitare il codice personalizzato per un connettore e quindi caricare un file .cs o .csx valido contenente il codice. È possibile fornire solo una classe di script per il connettore, che deve gestire le azioni impostate per il connettore. A tale scopo, controllare OperationId dell'oggetto Context per determinare se si desidera trasformare il codice o inoltrarlo al servizio sottostante. Nell'esempio seguente viene illustrato questo passaggio.
if (this.Context.OperationId != "CreateProduct")
{
return await this.HandleForwardOperation().ConfigureAwait(false);
}
In questo esempio, qualsiasi azione diversa da CreateProduct verrebbe inoltrata senza trasformazione. Questo approccio assicura che, se vengono impostate azioni impreviste per eseguire il codice, queste vengano inoltrate e non trasformate.
È inoltre possibile controllare su quali operazioni eseguire il codice personalizzato impostandolo in modo che venga eseguito per operazioni specifiche. Per impostazione predefinita, dopo che il codice è stato abilitato, tutte le operazioni eseguiranno il codice personalizzato. L'immagine seguente mostra che solo AddInvoice e GetInvoice eseguono il codice personalizzato.
Se si cercano questi valori in un connettore esportato, li si trova archiviati nel file apiProperties.json.
"scriptOperations": [
"AddInvoice”,
"GetInvoice”
],
Assicurarsi che la selezione delle operazioni che eseguono il codice personalizzato corrisponda alle aspettative dei controlli condizionali presenti nel codice. In mancanza di questa sincronizzazione, è frequente il caso che il codice personalizzato non venga eseguito o si verifichino errori imprevisti. Se il connettore ha rilevato errori, verificare che la definizione del connettore e il codice dello script prevedano l'elaborazione delle stesse operazioni.
La parte restante del modulo approfondisce l'argomento della creazione di trasformazioni di codice personalizzato che è possibile implementare con i connettori personalizzati.