Membuat konektor bawaan kustom untuk aplikasi logika Standar di Azure Logic Apps penyewa tunggal

Berlaku pada: Azure Logic Apps (Standar)

Jika Anda memerlukan konektor yang tidak tersedia di alur kerja aplikasi logika Standar, Anda dapat membuat konektor bawaan Anda sendiri menggunakan model ekstensibilitas yang sama yang digunakan oleh konektor bawaan berbasis penyedia layanan yang tersedia untuk alur kerja Standar di Azure Logic Apps penyewa tunggal. Model ekstensibilitas ini didasarkan pada model ekstensibilitas Azure Functions.

Artikel ini memperlihatkan cara membuat contoh konektor Azure Cosmos DB bawaan kustom, yang memiliki satu pemicu berbasis Azure Functions dan tanpa tindakan. Pemicu diaktifkan saat dokumen baru ditambahkan ke koleksi sewa atau kontainer di Azure Cosmos DB lalu menjalankan alur kerja yang menggunakan payload input sebagai dokumen Azure Cosmos DB.

Operasi	Detail operasi	Deskripsi
Pemicu	Saat dokumen diterima	Operasi pemicu ini berjalan ketika operasi penyisipan terjadi dalam database dan koleksi Azure Cosmos DB yang ditentukan.
Tindakan	Tidak ada	Konektor ini tidak menentukan operasi tindakan apa pun.

Konektor sampel ini menggunakan fungsionalitas yang sama dengan Pemicu Azure Cosmos DB untuk Azure Functions, yang didasarkan pada Pemicu dan pengikatan Azure Functions. Untuk sampel lengkap, tinjau Sampel konektor Azure Cosmos DB bawaan kustom - Ekstensi Konektor Azure Logic Apps.

Untuk informasi selengkapnya, baca dokumentasi berikut ini:

• Konektor kustom untuk aplikasi logika Standar
• Konektor bawaan berbasis penyedia layanan
• Azure Logic Apps penyewa tunggal

Prasyarat

• Akun dan langganan Azure. Jika Anda tidak memiliki langganan, daftar untuk akun Azure gratis.

• Pengetahuan dasar tentang Azure Logic Apps penyewa tunggal, alur kerja aplikasi logika Standar, konektor, dan cara menggunakan Visual Studio Code untuk membuat alur kerja berbasis penyewa tunggal. Untuk informasi selengkapnya, baca dokumentasi berikut ini:

  • Lingkungan penyewa tunggal versus multi penyewa dan layanan integrasi untuk Azure Logic Apps

  • Membuat alur kerja integrasi dengan Azure Logic Apps penyewa tunggal (Standar) - portal Azure

• Visual Studio Code dengan ekstensi Azure Logic Apps (Standar) dan prasyarat lainnya yang terinstal. Penginstalan Anda harus sudah menyertakan paket NuGet untuk Microsoft.Azure.Workflows.WebJobs.Extension.

  Catatan

  Kemampuan penulisan saat ini hanya tersedia di Visual Studio Code.

• Akun, database, dan kontainer atau koleksi Azure Cosmos DB. Untuk informasi selengkapnya, tinjau Mulai Cepat: Membuat akun, database, kontainer, dan item Azure Cosmos DB dari portal Azure.

Langkah-langkah tingkat tinggi

Kerangka berikut menjelaskan langkah-langkah tingkat tinggi untuk membangun konektor contoh:

1. Membuat proyek pustaka kelas.

2. Dalam proyek Anda, tambahkan paket NuGet Microsoft.Azure.Workflows.WebJobs.Extension sebagai referensi NuGet.

3. Berikan operasi untuk konektor bawaan Anda dengan menggunakan paket NuGet untuk mengimplementasikan metode untuk antarmuka bernama IServiceOperationsProvider dan IServiceOperationsTriggerProvider.

4. Daftarkan konektor bawaan kustom Anda dengan ekstensi runtime Azure Functions.

5. Instal konektor untuk digunakan.

Membuat proyek pustaka kelas Anda

1. Di Visual Studio Code, buat proyek pustaka kelas .NET Core 3.1.

2. Dalam proyek Anda, tambahkan paket NuGet bernama Microsoft.Azure.Workflows.WebJobs.Extension sebagai referensi NuGet.

Mengimplementasikan antarmuka penyedia layanan

Untuk menyediakan operasi untuk sampel konektor bawaan, dalam paket NuGet Microsoft.Azure.Workflows.WebJobs.Extension, diimplementasikan metode untuk antarmuka berikut. Diagram berikut menampilkan antarmuka dengan implementasi metode yang diharapkan oleh perancang dan runtime Azure Logic Apps untuk konektor bawaan kustom yang memiliki pemicu berbasis Azure Functions:

IServiceOperationsProvider

Antarmuka ini mencakup metode berikut yang menyediakan manifes operasi dan melakukan tugas spesifik penyedia layanan Anda atau logika bisnis aktual di konektor bawaan kustom Anda. Untuk informasi selengkapnya, tinjau IServiceOperationsProvider.

• GetService()

  Perancang di Azure Logic Apps memerlukan metode GetService() untuk mengambil metadata tingkat tinggi untuk layanan kustom Anda, termasuk deskripsi layanan, parameter input koneksi yang diperlukan pada perancang, kemampuan, warna merek, URL ikon, dan sebagainya.

• GetOperations()

  Perancang dalam Azure Logic Apps memerlukan metode GetOperations() untuk mengambil operasi yang diimplementasikan oleh layanan kustom Anda. Daftar operasi didasarkan pada skema Swagger. Perancang juga menggunakan metadata operasi untuk memahami parameter input untuk operasi tertentu dan menghasilkan output sebagai token properti, berdasarkan skema output untuk operasi.

• GetBindingConnectionInformation()

  Jika pemicu Anda adalah jenis pemicu berbasis Azure Functions, runtime dalam Azure Logic Apps memerlukan metode GetBindingConnectionInformation() untuk memberikan informasi parameter koneksi yang diperlukan ke pengikatan pemicu Azure Functions.

• InvokeOperation()

  Jika konektor Anda memiliki tindakan, runtime di Azure Logic Apps memerlukan metode InvokeOperation() untuk memanggil setiap tindakan di konektor Anda yang berjalan selama eksekusi alur kerja. Jika konektor Anda tidak memiliki tindakan, Anda tidak perlu mengimplementasikan metode InvokeOperation().

  Dalam contoh ini, konektor bawaan kustom Azure Cosmos DB tidak memiliki tindakan. Namun, metode ini disertakan dalam contoh ini untuk kelengkapan.

Untuk informasi selengkapnya tentang metode ini dan implementasinya, tinjau metode ini nanti di artikel ini.

IServiceOperationsTriggerProvider

Anda dapat menambahkan atau mengekspos pemicu atau tindakan Azure Functions sebagai pemicu penyedia layanan di konektor bawaan kustom Anda. Untuk menggunakan jenis pemicu berbasis Azure Functions dan pengikatan Azure Functions yang sama sebagai pemicu konektor terkelola Azure, implementasikan metode berikut untuk memberikan informasi koneksi dan pengikatan pemicu seperti yang diminta oleh Azure Functions. Untuk informasi selengkapnya, tinjau IServiceOperationsTriggerProvider.

• Metode GetFunctionTriggerType() diperlukan untuk mengembalikan string yang sama dengan parameter jenis dalam pengikatan pemicu Azure Functions.

• GetFunctionTriggerDefinition() memiliki implementasi default, jadi Anda tidak perlu mengimplementasikan metode ini secara eksplisit. Namun, jika Anda ingin memperbarui perilaku default pemicu, seperti memberikan parameter tambahan yang tidak diekspos perancang, Anda dapat mengimplementasikan metode ini dan mengambil alih perilaku default.

Metode untuk mengimplementasikan

Bagian berikut menjelaskan metode yang diimplementasikan konektor contoh. Untuk sampel lengkap, tinjau Sampel CosmosDbServiceOperationProvider.cs.

GetService()

Perancang memerlukan metode berikut untuk mendapatkan deskripsi tingkat tinggi untuk layanan Anda:

public ServiceOperationApi GetService()
{
   return this.CosmosDBApis.ServiceOperationServiceApi();
}

GetOperations()

Perancang memerlukan metode berikut untuk mengimplementasikan operasi oleh layanan Anda. Daftar operasi ini didasarkan pada skema Swagger.

public IEnumerable<ServiceOperation> GetOperations(bool expandManifest)
{
   return expandManifest ? serviceOperationsList : GetApiOperations();
}

GetBindingConnectionInformation()

Untuk menggunakan jenis pemicu berbasis Azure Functions, metode berikut menyediakan informasi parameter koneksi yang diperlukan ke pengikatan pemicu Azure Functions.

public string GetBindingConnectionInformation(string operationId, InsensitiveDictionary<JToken> connectionParameters)
{
   return ServiceOperationsProviderUtilities
      .GetRequiredParameterValue(
         serviceId: ServiceId,
         operationId: operationID,
         parameterName: "connectionString",
         parameters: connectionParameters)?
      .ToValue<string>();
}

InvokeOperation()

Contoh konektor bawaan kustom Azure Cosmos DB tidak memiliki tindakan, tetapi metode berikut disertakan untuk kelengkapan:

public Task<ServiceOperationResponse> InvokeOperation(string operationId, InsensitiveDictionary<JToken> connectionParameters, ServiceOperationRequest serviceOperationRequest)
{
   throw new NotImplementedException();
}

GetFunctionTriggerType()

Untuk menggunakan pemicu berbasis Azure Functions sebagai pemicu di konektor, Anda harus mengembalikan string yang sama dengan parameter jenis dalam pengikatan pemicu Azure Functions.

Contoh berikut mengembalikan string untuk pemicu Azure Cosmos DB bawaan siap pakai, "type": "cosmosDBTrigger":

public string GetFunctionTriggerType()
{
   return "CosmosDBTrigger";
}

GetFunctionTriggerDefinition()

Metode ini memiliki implementasi default, jadi Anda tidak perlu menerapkan metode ini secara eksplisit. Namun, jika Anda ingin memperbarui perilaku default pemicu, seperti memberikan parameter tambahan yang tidak diekspos perancang, Anda dapat mengimplementasikan metode ini dan mengambil alih perilaku default.

Mendaftarkan konektor Anda

Untuk memuat ekstensi konektor bawaan kustom Anda selama runtime Azure Functions, Anda harus menambahkan pendaftaran ekstensi Azure Functions sebagai pekerjaan startup dan mendaftarkan konektor Anda sebagai penyedia layanan dalam daftar penyedia layanan. Berdasarkan jenis data yang dibutuhkan pemicu bawaan Anda sebagai input, secara opsional tambahkan pengonversi. Contoh ini mengonversi jenis data Dokumen untuk dokumen Azure Cosmos DB menjadi array JObject .

Bagian berikut menunjukkan cara mendaftarkan konektor bawaan kustom Anda sebagai ekstensi Azure Functions.

Membuat pekerjaan startup

1. Buat kelas startup menggunakan atribut rakitan bernama [assembly:WebJobsStartup].

2. Implementasikan antarmuka IWebJobsStartup. Dalam metode Configure(), daftarkan ekstensi dan masukkan penyedia layanan.

   Misalnya, cuplikan kode berikut menunjukkan implementasi kelas startup untuk contoh konektor Azure Cosmos DB bawaan kustom:

   using Microsoft.Azure.WebJobs;
   using Microsoft.Azure.WebJobs.Hosting;
   using Microsoft.Extensions.DependencyInjection.Extensions;
   
   [assembly: Microsoft.Azure.WebJobs.Hosting.WebJobsStartup(typeof(ServiceProviders.CosmosDb.Extensions.CosmosDbTriggerStartup))]
   
   namespace ServiceProviders.CosmosDb.Extensions
   {
      public class CosmosDbServiceProviderStartup : IWebJobsStartup
      {
         // Initialize the workflow service.
         public void Configure(IWebJobsBuilder builder)
         {
               // Register the extension.
               builder.AddExtension<CosmosDbServiceProvider>)();
   
               // Use dependency injection (DI) for the trigger service operation provider.
               builder.Services.TryAddSingleton<CosmosDbTriggerServiceOperationsProvider>();
         }
      }
   }
   

   Untuk informasi selengkapnya, tinjau Mendaftarkan layanan - Menggunakan injeksi dependensi di .NET Azure Functions.

Mendaftarkan penyedia layanan

Sekarang, daftarkan implementasi penyedia layanan sebagai ekstensi Azure Functions dengan mesin Azure Logic Apps. Contoh ini menggunakan pemicu Azure Cosmos DB untuk Azure Functions bawaan sebagai pemicu baru. Contoh ini juga mendaftarkan penyedia layanan Azure Cosmos DB baru untuk daftar penyedia layanan yang sudah ada, yang sudah menjadi bagian dari ekstensi Azure Logic Apps. Untuk informasi selengkapnya, lihat Mendaftarkan ekstensi pengikatan Azure Functions.

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs.Description;
using Microsoft.Azure.WebJobs.Host.Config;
using Microsoft.Azure.Workflows.ServiceProviders.Abstractions;
using Microsoft.WindowsAzure.ResourceStack.Common.Extensions;
using Microsoft.WindowsAzure.ResourceStack.Common.Json;
using Microsoft.WindowsAzure.ResourceStack.Common.Storage.Cosmos;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;

namespace ServiceProviders.CosmosDb.Extensions
{
   [Extension("CosmosDbServiceProvider", configurationSection: "CosmosDbServiceProvider")]
   public class CosmosDbServiceProvider : IExtensionConfigProvider
   {
      // Initialize a new instance for the CosmosDbServiceProvider class.
      public CosmosDbServiceProvider(ServiceOperationsProvider serviceOperationsProvider, CosmosDbTriggerServiceOperationsProvider operationsProvider)
      {
         serviceOperationsProvider.RegisterService(serviceName: CosmosDBServiceOperationsProvider.ServiceName, serviceOperationsProviderId: CosmosDBServiceOperationsProvider.ServiceId, serviceOperationsProviderInstance: operationsProvider);
      }

      // Convert the Azure Cosmos DB Document array to a generic JObject array.
      public static JObject[] ConvertDocumentToJObject(IReadOnlyList<Document> data)
      {
         List<JObject> jobjects = new List<JObject>();

         foreach(var doc in data)
         {
            jobjects.Add((JObject)doc.ToJToken());
         }

         return jobjects.ToArray();
      }

      // In the Initialize method, you can add any custom implementation.
      public void Initialize(ExtensionConfigContext context)
      {
         // Convert the Azure Cosmos DB Document list to a JObject array.
         context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);
      }
   }
}

Menambahkan pengonversi

Azure Logic Apps memiliki cara umum untuk menangani pemicu bawaan Azure Functions dengan menggunakan array JObject. Namun, jika Anda ingin mengonversi daftar baca-saja dari dokumen Azure Cosmos DB menjadi array JObject, Anda dapat menambahkan pengonversi. Ketika pengonversi siap, daftarkan pengonversi sebagai bagian dari ExtensionConfigContext seperti yang ditunjukkan sebelumnya dalam contoh ini:

// Convert the Azure Cosmos DB  document list to a JObject array.
context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);

Diagram pustaka kelas untuk kelas yang diimplementasikan

Setelah selesai, tinjau diagram kelas berikut yang menunjukkan implementasi untuk semua kelas dalam bundel ekstensi Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll:

• CosmosDbServiceOperationsProvider
• CosmosDbServiceProvider
• CosmosDbServiceProviderStartup

Menginstal konektor Anda

Untuk menambahkan referensi NuGet dari bagian sebelumnya, di bundel ekstensi bernama Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, perbarui file extensions.json. Untuk informasi selengkapnya, buka repositori Azure/logicapps-connector-extensions, dan tinjau skrip PowerShell bernama add-extension.ps1.

1. Perbarui bundel ekstensi untuk menyertakan konektor bawaan kustom.

2. Di Visual Studio Code, yang seharusnya memiliki ekstensi Azure Logic Apps (Standar) untuk Visual Studio Code terinstal, buat proyek aplikasi logika, dan instal paket ekstensi menggunakan perintah PowerShell berikut:

   PowerShell

   dotnet add package "Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB" --version 1.0.0  --source $extensionPath
   

   Atau, dari direktori proyek aplikasi logika Anda menggunakan perintah PowerShell, jalankan skrip PowerShell bernama add-extension.ps1:

   .\add-extension.ps1 {Cosmos-DB-output-bin-NuGet-folder-path} CosmosDB
   

   Bash

   Untuk menggunakan Bash, dari direktori proyek aplikasi logika Anda, jalankan skrip PowerShell dengan perintah berikut:

   powershell -file add-extension.ps1 {Cosmos-DB-output-bin-NuGet-folder-path} CosmosDB
   

   Jika ekstensi untuk konektor bawaan kustom Anda berhasil diinstal, Anda mendapatkan output yang terlihat mirip dengan contoh berikut:

   C:\Users\{your-user-name}\Desktop\demoproj\cdbproj>powershell - file C:\myrepo\github\logicapps-connector-extensions\src\Common\tools\add-extension.ps1 C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\CosmosDB
   
   Nuget extension path is C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\
   Extension dll path is C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\netcoreapp3.1\Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll
   Extension bundle module path is C:\Users\{your-user-name}\.azure-functions-core-tools\Functions\ExtensionBundles\Microsoft.Azure.Functions.ExtensionBundle.Workflows1.1.9
   EXTENSION PATH is C:\Users\{your-user-name}\.azure-functions-core-tools\Functions\ExtensionBundles\Microsoft.Azure.Functions.ExtensionBundle.Workflows\1.1.9\bin\extensions.json and dll Path is C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\netcoreapp3.1\Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll
   SUCCESS: The process "func.exe" with PID 26692 has been terminated.
      Determining projects to restore...
      Writing C:\Users\{your-user-name}\AppData\Local\Temp\tmpD343.tmp`<br>
   info : Adding PackageReference for package 'Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB' into project 'C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj'.
   info : Restoring packages for C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj...
   info : Package 'Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB' is compatible with all the specified frameworks in project 'C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj'.
   info : PackageReference for package 'Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB' version '1.0.0' updated in file 'C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj'.
   info : Committing restore...
   info : Generating MSBuild file C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\obj\cdbproj.csproj.nuget.g.props.
   info : Generating MSBuild file C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\obj\cdbproj.csproj.nuget.g.targets.
   info : Writing assets file to disk. Path: C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\obj\project.assets.json.
   log : Restored C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\cdbproj.csproj (in 1.5 sec).
   Extension CosmosDB is successfully added.
   
   C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\>
   

3. Jika ada proses func.exe yang berjalan, pastikan untuk menutup atau keluar dari proses tersebut sebelum Anda melanjutkan ke langkah berikutnya.

Uji koneksi Anda

1. Di Visual Studio Code, buka aplikasi logika Standar dan alur kerja kosong di perancang.

2. Pada permukaan perancang, pilih Pilih operasi untuk membuka pemilih operasi konektor.

3. Di bawah kotak pencarian perancang, pilih Bawaan. Di kotak pencarian, masukkan cosmos db.

   Pemilih operasi menunjukkan konektor dan pemicu bawaan kustom Anda, misalnya:

   

4. Dari daftar Pemicu, pilih pemicu bawaan kustom Anda untuk memulai alur kerja Anda.

5. Pada panel koneksi, berikan nilai properti berikut untuk membuat koneksi, misalnya:

   Properti	Diperlukan	Nilai	Deskripsi
   Nama Koneksi	Ya	<Azure-Cosmos-DB-connection-name>	Nama untuk koneksi Azure Cosmos DB yang akan dibuat
   String Koneksi	Ya	<Azure Cosmos DB-DB-connection-string>	String koneksi untuk koleksi database Azure Cosmos DB atau koleksi sewa tempat Anda ingin menambahkan setiap dokumen baru yang diterima.

   

6. Jika sudah selesai, pilih Buat.

7. Pada panel properti pemicu, berikan nilai properti berikut untuk pemicu Anda, misalnya:

   Properti	Diperlukan	Nilai	Deskripsi
   Nama database	Ya	<Azure-Cosmos-DB-database-name>	Nama untuk database Azure Cosmos DB yang akan digunakan
   Nama koleksi	Ya	<Nama koleksi Azure-Cosmos-DB>	Nama untuk koleksi Azure Cosmos DB tempat Anda ingin menambahkan setiap dokumen baru yang diterima.

   

   Untuk contoh ini, dalam tampilan kode, definisi alur kerja, yang ada di file workflow.json, memiliki triggers objek JSON yang tampak mirip dengan sampel berikut:

   {
      "definition": {
         "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
         "actions": {},
         "contentVersion": "1.0.0.0",
         "outputs": {},
         "triggers": {
            "When_a_document_is_received": {
               "inputs":{
                  "parameters": {
                     "collectionName": "States",
                     "databaseName": "SampleCosmosDB"
                  },
                  "serviceProviderConfiguration": {
                     "connectionName": "cosmosDb",
                     "operationId": "whenADocumentIsReceived",
                     "serviceProviderId": "/serviceProviders/CosmosDb"
                  },
                  "splitOn": "@triggerOutputs()?['body']",
                  "type": "ServiceProvider"
               }
            }
         }
      },
      "kind": "Stateful"
   }
   

   Definisi koneksi, yang ada dalam file connections.json, memiliki serviceProviderConnections objek JSON yang tampak mirip dengan sampel berikut:

   {
      "serviceProviderConnections": {
         "cosmosDb": {
            "parameterValues": {
               "connectionString": "@appsetting('cosmosDb_connectionString')"
            },
            "serviceProvider": {
               "id": "/serviceProviders/CosmosDb"
            },
            "displayName": "myCosmosDbConnection"
         }
      },
      "managedApiConnections": {}
   }
   

8. Pada Visual Studio Code, pada menu Jalankan, pilih Mulai Penelusuran Kesalahan. (Tekan F5)

9. Untuk memicu alur kerja Anda, di portal Azure, buka akun Azure Cosmos DB Anda. Di menu akun, pilih Data Explorer. Telusuri ke database dan koleksi yang Anda tentukan dalam pemicu. Tambahkan item ke koleksi.

   

Langkah berikutnya

• Sumber untuk sampel konektor Azure Cosmos DB bawaan kustom - Ekstensi Konektor Azure Logic Apps

• Pemicu Azure Service Bus bawaan: pembuatan batch dan penanganan sesi