Elaborare e creare documenti di Azure Cosmos DB usando App per la logica di Azure

Si applica a: App per la logica di Azure (a consumo e standard)

Dal flusso di lavoro in App per la logica di Azure è possibile connettersi ad Azure Cosmos DB e usare i documenti usando il connettore Azure Cosmos DB. Questo connettore fornisce trigger e azioni che il flusso di lavoro può usare per le operazioni di Azure Cosmos DB. Ad esempio, le azioni includono la creazione o l'aggiornamento, la lettura, l'esecuzione di query e l'eliminazione di documenti.

È possibile connettersi ad Azure Cosmos DB da entrambi i tipi di risorse app per la logica (consumo) e app per la logica (standard) usando le operazioni del connettore gestito. Per App per la logica (Standard), Azure Cosmos DB offre anche operazioni predefinite , attualmente in anteprima e offrono funzionalità diverse, prestazioni migliori e velocità effettiva più elevata. Ad esempio, se si usa il tipo di risorsa App per la logica (Standard), è possibile usare il trigger predefinito per rispondere alle modifiche in un contenitore di Azure Cosmos DB. È possibile combinare le operazioni di Azure Cosmos DB con altre azioni e trigger nei flussi di lavoro dell'app per la logica per abilitare scenari come l'origine eventi e l'elaborazione dati generale.

Limiti

• Attualmente, solo i flussi di lavoro con stato in una risorsa app per la logica (Standard) possono usare sia le operazioni del connettore gestito che le operazioni predefinite. I flussi di lavoro senza stato possono usare solo operazioni predefinite.

• Il connettore Azure Cosmos DB supporta solo gli account Azure Cosmos DB creati con Azure Cosmos DB per NoSQL.

Prerequisiti

• Account e sottoscrizione di Azure. Se non si ha una sottoscrizione di Azure, iscriversi per creare un account Azure gratuito.

• Un account Azure Cosmos DB.

• Flusso di lavoro dell'app per la logica da cui si vuole accedere all'account Azure Cosmos DB. Per usare il trigger di Azure Cosmos DB, è necessario creare l'app per la logica usando il tipo di risorsa App per la logica (Standard) e aggiungere un flusso di lavoro vuoto.

Aggiungere un trigger di Azure Cosmos DB

In App per la logica di Azure ogni flusso di lavoro deve iniziare con un trigger, che viene generato quando si verifica un evento specifico o quando viene soddisfatta una condizione specifica.

Se si usa il tipo di risorsa App per la logica (Standard), il trigger predefinito denominato Quando viene creato o modificato un elemento (anteprima) è disponibile ed è basato sul modello di feed di modifiche di Azure Cosmos DB. Questo trigger non è disponibile per il tipo di risorsa App per la logica (consumo).

Consumo

Non sono disponibili trigger di Azure Cosmos DB per il tipo di risorsa App per la logica (consumo).

Standard

Per aggiungere un trigger predefinito di Azure Cosmos DB a un flusso di lavoro dell'app per la logica in App per la logica di Azure a tenant singolo, seguire questa procedura:

1. Nel portale di Azure, aprire il flusso di lavoro dell'app per la logica nella finestra di progettazione.

2. Per trovare il trigger, seguire questa procedura:

   1. Nella finestra di progettazione selezionare Scegli un'operazione.

   2. Dopo aver aperto il riquadro Aggiungi un trigger , nella casella di ricerca Scegliere un'operazione selezionare Predefinito.

   3. Nella casella di ricerca immettere Azure Cosmos DB. Nell'elenco dei trigger selezionare il trigger denominato Quando viene creato o modificato un elemento (anteprima).

   

3. Se vengono richiesti i dettagli della connessione, creare ora una connessione ad Azure Cosmos DB.

4. Nella scheda Parametri specificare le informazioni necessarie per il trigger.

   Proprietà	Richiesto	Valore	Descrizione
   Database Id	Sì	< database-name>	Nome del database con il contenitore da monitorare. Questo database deve avere anche il contenitore di lease. Se non si ha già un contenitore di lease, il connettore ne creerà uno in un passaggio successivo.
   ID contenitore monitorato	Sì	< container-name>	Nome del contenitore da monitorare. Questo contenitore deve esistere già nel database specificato.
   ID contenitore lease	Sì	< lease-container-name>	Nome di un contenitore di lease esistente o di un nuovo contenitore che si vuole creare automaticamente. Il trigger viene pre-compilato leases come nome predefinito comune.
   Creare un contenitore di lease	No	No o Sì	Se il contenitore di lease esiste già nel database specificato, selezionare No. Se si vuole che il trigger crei questo contenitore, selezionare Sì. Se si seleziona Sì e si usa la velocità effettiva manuale dedicata per ogni contenitore, assicurarsi di aprire l'elenco Aggiungi nuovo parametro per selezionare la proprietà Velocità effettiva del contenitore lease. Immettere il numero di unità richiesta (UR) di cui si vuole eseguire il provisioning per questo contenitore.

   L'immagine seguente mostra un trigger di esempio:

   

   Nota

   Il trigger creerà più esecuzioni del flusso di lavoro per ogni elemento creato o modificato in Azure Cosmos DB, quindi l'output del contenuto dinamico di questo trigger è sempre un singolo elemento.

5. Aggiungere qualsiasi altra azione che si vuole eseguire al flusso di lavoro.

6. Sulla barra degli strumenti della finestra di progettazione seleziona Salva.

Aggiungere un'azione di Azure Cosmos DB

In App per la logica di Azure, un'azione è un passaggio del flusso di lavoro che segue un trigger o un'altra azione. Il connettore Azure Cosmos DB offre azioni per i tipi di risorse app per la logica (consumo) e app per la logica (standard). Negli esempi seguenti per ogni tipo di risorsa viene illustrato come usare un'azione che crea o aggiorna un documento.

Consumo

Per aggiungere un'azione di Azure Cosmos DB a un flusso di lavoro dell'app per la logica in App per la logica di Azure multi-tenant, seguire questa procedura:

1. Nella portale di Azure aprire il flusso di lavoro nella finestra di progettazione.

2. Se il flusso di lavoro è vuoto, aggiungere qualsiasi trigger desiderato.

   Questo esempio inizia con il trigger Quando viene ricevuta una richiesta HTTP.

3. Nel trigger o nell'azione in cui si vuole aggiungere l'azione Azure Cosmos DB selezionare Nuovo passaggio o Aggiungi un'azione, se tra i passaggi.

4. Nella casella di ricerca della finestra di progettazione immettere Azure Cosmos DB. Selezionare l'azione Azure Cosmos DB da usare.

   In questo esempio viene usata l'azione denominata Crea o aggiorna documento (V3).

   

5. Se vengono richiesti i dettagli della connessione, creare ora una connessione all'account Azure Cosmos DB.

6. Fornire le informazioni necessarie per l'azione.

   Proprietà	Richiesto	Valore	Descrizione
   Nome dell'account Azure Cosmos DB	Sì	Selezionare Usa impostazioni di connessione (<Azure-Cosmos-DB-account-name>) oppure immettere manualmente il nome.	Nome dell'account Azure Cosmos DB.
   ID database	Sì	< database-ID>	Database che si desidera connettere.
   ID contenitore	Sì	< container-ID>	Contenitore su cui eseguire una query.
   Documento	Sì	< Documento JSON>	Documento JSON da creare. In questo esempio viene usato il corpo della richiesta dall'output del trigger. Suggerimento: se il token corpo del trigger HTTP non viene visualizzato nell'elenco di contenuto dinamico da aggiungere, accanto al nome del trigger, selezionare Visualizza altro. Nota: assicurarsi che il corpo sia json ben formato e, come minimo, contenga la proprietà e la id proprietà della chiave di partizione per il documento. Se esiste già un documento con la chiave di partizione e specificata id , il documento viene aggiornato. Altrimenti, viene creato un nuovo documento.

   L'immagine seguente mostra un'azione di esempio:

   

7. Configurare qualsiasi altra impostazione di azione in base alle esigenze.

8. Sulla barra degli strumenti della finestra di progettazione seleziona Salva.

9. Testare l'app per la logica per assicurarsi che il flusso di lavoro crei un documento nel contenitore specificato.

Standard

Per aggiungere un'azione di Azure Cosmos DB a un flusso di lavoro dell'app per la logica in App per la logica di Azure a tenant singolo, seguire questa procedura:

1. Nella portale di Azure aprire il flusso di lavoro nella finestra di progettazione.

2. Se il flusso di lavoro è vuoto, aggiungere qualsiasi trigger desiderato.

   Questo esempio inizia con il trigger Quando viene ricevuta una richiesta HTTP, che usa una definizione di schema di base per rappresentare l'elemento che si desidera creare.

   

3. Nel trigger o nell'azione in cui si vuole aggiungere l'azione Azure Cosmos DB selezionare Inserisci un nuovo passaggio (+) >Aggiungi un'azione.

4. Nella finestra di progettazione verificare che l'opzione Aggiungi un'operazione sia selezionata. Nel riquadro Aggiungi un'azione visualizzata, nella casella di ricerca Scegliere un'operazione selezionare Predefinita per trovare le azioni di Azure Cosmos DB.

   Nota

   Se si dispone di un flusso di lavoro con stato, le azioni del connettore gestito sono disponibili anche nella scheda Azure, ma usarle solo quando le azioni predefinite desiderate non sono disponibili.

5. Nella casella di ricerca immettere Azure Cosmos DB. Selezionare l'azione Azure Cosmos DB da usare.

   In questo esempio viene usata l'azione denominata Crea o aggiorna elemento (anteprima) che crea un nuovo elemento o aggiorna un elemento esistente.

   

6. Se vengono richiesti i dettagli della connessione, creare ora una connessione all'account Azure Cosmos DB.

7. Fornire le informazioni necessarie per l'azione.

   Proprietà	Richiesto	Valore	Descrizione
   Database Id	Sì	< database-ID>	Database che si desidera connettere.
   ID contenitore	Sì	< container-ID>	Contenitore su cui eseguire una query.
   Articolo	Sì	< Documento JSON>	Documento JSON da creare. In questo esempio viene usato il corpo della richiesta dall'output del trigger. Suggerimento: se il token corpo del trigger HTTP non viene visualizzato nell'elenco di contenuto dinamico da aggiungere, accanto al nome del trigger, selezionare Visualizza altro. Nota: assicurarsi che il corpo sia json ben formato e, come minimo, contenga la proprietà e la id proprietà della chiave di partizione per il documento. Se esiste già un documento con la chiave di partizione e specificata id , il documento viene aggiornato. Altrimenti, viene creato un nuovo documento.
   Chiave di partizione	No	< partition-key>	Valore della chiave di partizione per il documento che si desidera creare.

   L'immagine seguente mostra un'azione di esempio:

   

8. Configurare qualsiasi altra impostazione di azione in base alle esigenze.

9. Sulla barra degli strumenti della finestra di progettazione seleziona Salva.

10. Testare l'app per la logica per assicurarsi che il flusso di lavoro crei un documento nel contenitore specificato.

Connettersi ad Azure Cosmos DB

Quando si aggiunge un trigger o un'azione che si connette a un servizio o a un sistema e non si dispone di una connessione esistente o attiva, App per la logica di Azure richiede di fornire le informazioni di connessione, che variano in base al tipo di connessione, ad esempio:

• Credenziali dell'account
• Un nome da usare per la connessione
• Il nome del server o del sistema
• Tipo di autenticazione da usare
• Una stringa di connessione

Prima di poter configurare il trigger di Azure Cosmos DB o l'azione di Azure Cosmos DB, è necessario connettersi a un account di database.

Consumo

In un flusso di lavoro dell'app per la logica (consumo) una connessione di Azure Cosmos DB richiede i valori delle proprietà seguenti:

Proprietà	Richiesto	Valore	Descrizione
Nome connessione	Sì	< nome connessione>	Nome da usare per la connessione.
Tipo di autenticazione	Sì	< tipo di connessione>	Tipo di autenticazione che si vuole usare. In questo esempio viene usata la chiave di accesso. - Se si seleziona Chiave di accesso, specificare i valori di proprietà obbligatori rimanenti per creare la connessione. - Se si seleziona Microsoft Entra integrato, non sono necessari altri valori di proprietà, ma è necessario configurare la connessione seguendo la procedura per l'autenticazione di Microsoft Entra e il connettore Azure Cosmos DB.
Chiave di accesso all'account Azure Cosmos DB	Sì	< access-key>	Chiave di accesso per l'account Azure Cosmos DB da usare per questa connessione. Questo valore è una chiave di lettura/scrittura o una chiave di sola lettura. Nota: per trovare la chiave, passare alla pagina dell'account Azure Cosmos DB. Nel menu di spostamento, in Impostazioni, selezionare Chiavi. Copiare uno dei valori di chiave disponibili.
Account Id	Sì	< ID account>	Nome dell'account Azure Cosmos DB da usare per questa connessione.

L'immagine seguente mostra una connessione di esempio:

Nota

Dopo aver creato la connessione, se si dispone di una connessione di Azure Cosmos DB esistente che si vuole usare o se si vuole creare un'altra nuova connessione, selezionare Cambia connessione nell'editor dei dettagli del trigger o dell'azione.

Standard

In un flusso di lavoro dell'app per la logica (Standard) una connessione di Azure Cosmos DB richiede i valori delle proprietà seguenti:

Proprietà	Richiesto	Valore	Descrizione
Nome connessione	Sì	< nome connessione>	Nome da usare per la connessione.
Stringa di connessione	Sì	< connection-string>	Azure Cosmos DB stringa di connessione da usare per la connessione. Nota: per trovare il stringa di connessione, passare alla pagina dell'account Azure Cosmos DB. Nel menu di spostamento, in Impostazioni, selezionare Chiavi. Copiare uno dei valori di stringa di connessione disponibili.

L'immagine seguente mostra una connessione di esempio:

Nota

Dopo aver creato la connessione, se si dispone di una connessione di Azure Cosmos DB esistente che si vuole usare o se si vuole creare un'altra nuova connessione, selezionare Cambia connessione nell'editor dei dettagli del trigger o dell'azione.

Informazioni di riferimento sui connettori

Per informazioni di riferimento sulle operazioni del connettore gestito di Azure Cosmos DB, ad esempio trigger, azioni e limiti, vedere la pagina di riferimento del connettore.

Non esiste alcuna pagina di riferimento corrispondente per le operazioni predefinite di Azure Cosmos DB. Per altre informazioni, vedere invece la tabella seguente:

Type	Nome	Parametri
Trigger	Quando viene creato o modificato un elemento	- ID database: obbligatorio. Nome del database con i contenitori monitorati e lease. - ID contenitore monitorato: obbligatorio. Nome del contenitore monitorato. - ID contenitore lease: obbligatorio. Nome del contenitore usato per archiviare i lease. - Creare un contenitore di lease: obbligatorio. Se true, creare il contenitore di lease se non è già esistente. - Velocità effettiva del contenitore lease: facoltativa. Numero di unità richiesta da assegnare quando viene creato il contenitore di lease.
Azione	Creare o aggiornare un elemento	- ID database: obbligatorio. Nome del database. - ID contenitore: obbligatorio. Nome del contenitore. - Elemento: obbligatorio. Elemento da creare o aggiornare. - Chiave di partizione: facoltativa. Valore della chiave di partizione per l'elemento richiesto. - Is Upsert: facoltativo. Se true, sostituire l'elemento, se esistente. In caso contrario, creare l'elemento.
Azione	Creare o aggiornare molti elementi in blocco	Questa azione è ottimizzata per scenari con velocità effettiva elevata e prevede un'elaborazione aggiuntiva prima che l'azione invii gli elementi da creare nel contenitore Azure Cosmos DB. Per un numero elevato di elementi, questa elaborazione aggiuntiva accelera il tempo totale della richiesta. Per un numero ridotto di elementi, questo sovraccarico aggiuntivo può causare prestazioni più lente rispetto all'uso di più azioni di creazione di elementi singoli. - ID database: obbligatorio. Nome del database. - ID contenitore: obbligatorio. Nome del contenitore. - Elementi: obbligatorio. Matrice di elementi da creare o aggiornare. - Is Upsert: facoltativo. Se true, sostituire un elemento se esistente. In caso contrario, creare l'elemento.
Azione	Leggere un elemento	- ID database: obbligatorio. Nome del database. - ID contenitore: obbligatorio. Nome del contenitore. - ID elemento: obbligatorio. Valore id dell'elemento richiesto. - Chiave di partizione: obbligatorio. Valore della chiave di partizione per l'elemento richiesto.
Azione	Eliminare un elemento	- ID database: obbligatorio. Nome del database. - ID contenitore obbligatorio. Nome del contenitore. - ID elemento: obbligatorio. Valore id dell'elemento richiesto. - Chiave di partizione: obbligatorio. Valore della chiave di partizione per l'elemento richiesto.
Azione	Eseguire query sugli elementi	- ID database: obbligatorio. Nome del database. - ID contenitore: obbligatorio. Nome del contenitore. - Query SQL: obbligatorio. Testo della query SQL di Azure Cosmos DB. - Chiave di partizione: facoltativa. Valore della chiave di partizione per la richiesta, se presente. - Token di continuazione: facoltativo. Token di continuazione per questa query fornita dal servizio Azure Cosmos DB, se presente. - Numero massimo di elementi: facoltativo. Numero massimo di elementi da restituire per la query.

Procedure consigliate per le operazioni predefinite di Azure Cosmos DB

Ottenere risultati iterabili dall'azione Elementi di query

L'azione predefinita Elementi di query in un flusso di lavoro dell'app per la logica (Standard) include molti output di contenuto dinamico disponibili per l'uso nelle azioni successive. Per ottenere gli elementi dei risultati della query o i metadati degli elementi come oggetto iterabile, seguire questa procedura:

1. Nella portale di Azure aprire il flusso di lavoro nella finestra di progettazione.

2. Se il flusso di lavoro è vuoto, aggiungere qualsiasi trigger desiderato.

   Questo esempio inizia con il trigger Ricorrenza.

3. Nel trigger o nell'azione in cui si vuole aggiungere l'azione Azure Cosmos DB selezionare Inserisci un nuovo passaggio (+) >Aggiungi un'azione.

4. Nella finestra di progettazione verificare che l'opzione Aggiungi un'operazione sia selezionata. Nel riquadro Aggiungi un'azione visualizzata, nella casella di ricerca Scegliere un'operazione selezionare Predefinita per trovare le azioni di Azure Cosmos DB.

5. Nella casella di ricerca immettere Azure Cosmos DB. Selezionare l'azione Elementi query (anteprima).

6. Se vengono richiesti i dettagli della connessione, creare una connessione all'account Azure Cosmos DB.

7. Fornire le informazioni necessarie per l'azione.

   Proprietà	Obbligatorio	Valore	Descrizione
   Database Id	Sì	< database-ID>	Database che si desidera connettere.
   ID contenitore	Sì	< container-ID>	Contenitore su cui eseguire una query.
   Query SQL	Sì	< sql-query>	Query SQL per la richiesta.

   L'immagine seguente mostra un'azione di esempio:

   

8. Configurare qualsiasi altra impostazione di azione in base alle esigenze.

9. Nell'azione selezionare Inserisci un nuovo passaggio (+) >Aggiungi un'azione. Nel riquadro Aggiungi un'azione visualizzata selezionare l'azione da eseguire in tutti gli elementi dei risultati della query.

Questo esempio usa l'azione predefinita di Azure Cosmos DB denominata Elimina un elemento (anteprima).This example use the Azure Cosmos DB built-in action named Delete an item (preview).

1. Nell'azione aggiunta in precedenza è possibile accedere ai dati dall'output dell'azione di query. Fare clic all'interno di uno dei campi di input dell'azione in modo che venga visualizzato l'elenco di contenuto dinamico. Selezionare uno degli elementi di risposta disponibili o selezionare Visualizza altro per altre opzioni.

In questo esempio viene usato l'ID dell'elemento di risposta nel campo ID elemento per popolare gli ID in base ai risultati della query.

1. Dopo aver selezionato un elemento della risposta, l'azione For each viene aggiunta automaticamente per scorrere tutti i risultati della query. Il ciclo For each contiene l'azione aggiunta in precedenza. È possibile aggiungere qualsiasi altra azione che si desidera eseguire nel ciclo.

2. Sulla barra degli strumenti della finestra di progettazione seleziona Salva.

3. Testare l'app per la logica per assicurarsi che il flusso di lavoro restituisca l'output previsto.

Passaggi successivi

• Connettori gestiti per app per la logica di Azure
• Connettori predefiniti per App per la logica di Azure
• Cosa sono i connettori gestiti in App per la logica di Azure