Menyambungkan Azure Functions ke Azure Cosmos DB menggunakan Visual Studio Code

Artikel
04/27/2024

Azure Functions memungkinkan Anda tersambung ke layanan dan sumber daya lainnya agar berfungsi tanpa harus menulis kode integrasi Anda sendiri. Pengikatanini, yang mewakili input dan output, dinyatakan dalam definisi fungsi. Data dari pengikatan diberikan ke fungsi sebagai parameter. Pemicu adalah jenis pengikatan input khusus. Meskipun fungsi hanya memiliki satu pemicu, fungsi dapat memiliki beberapa pengikatan input dan output. Untuk mempelajari lebih lanjut, lihat pemicu dan pengikatan Azure Functions.

Artikel ini memberikan informasi tentang cara menggunakan Visual Studio Code untuk menyambungkan Azure Cosmos DB ke fungsi yang Anda buat di artikel mulai cepat sebelumnya. Pengikatan output yang Anda tambahkan ke fungsi ini menulis data dari permintaan HTTP ke dokumen JSON yang disimpan dalam kontainer Azure Cosmos DB.

Sebelum memulai, Anda harus menyelesaikan mulai cepat: Membuat fungsi C# di Azure menggunakan Visual Studio Code. Jika Anda sudah membersihkan sumber daya di akhir artikel tersebut, lakukan lagi langkah-langkahnya untuk membuat ulang aplikasi fungsi dan sumber daya terkait di Azure.

Sebelum memulai, Anda harus menyelesaikan mulai cepat: Membuat fungsi JavaScript di Azure menggunakan Visual Studio Code. Jika Anda sudah membersihkan sumber daya di akhir artikel tersebut, lakukan lagi langkah-langkahnya untuk membuat ulang aplikasi fungsi dan sumber daya terkait di Azure.

Catatan

Artikel ini saat ini hanya mendukung Node.js v3 untuk Functions.

Sebelum memulai, Anda harus menyelesaikan mulai cepat: Membuat fungsi Python di Azure menggunakan Visual Studio Code. Jika Anda sudah membersihkan sumber daya di akhir artikel tersebut, lakukan lagi langkah-langkahnya untuk membuat ulang aplikasi fungsi dan sumber daya terkait di Azure.

Mengkonfigurasikan lingkungan Anda

Sebelum memulai, pastikan untuk menginstal ekstensi Database Azure untuk Visual Studio Code.

Membuat akun Azure Cosmos DB

Sekarang, Anda membuat akun Azure Cosmos DB sebagai jenis akun tanpa server. Mode berbasis konsumsi ini menjadikan Azure Cosmos DB pilihan yang tepat untuk beban kerja tanpa server.

Di Visual Studio Code, pilih Tampilkan>Palet Perintah... lalu di pencarian palet perintah untuk Azure Databases: Create Server...

Berikan informasi berikut pada permintaan:

Prompt	Pilihan
Pilih Server Azure Database	Pilih Core (NoSQL) untuk membuat database dokumen yang bisa Anda kueri dengan menggunakan sintaks SQL atau Salinan Kueri (Pratinjau) yang mengonversi perintah bahasa alami menjadi kueri. Pelajari selengkapnya tentang Azure Cosmos DB.
Nama akun	Masukkan nama unik untuk mengidentifikasi akun Azure Cosmos DB Anda. Nama akun hanya dapat menggunakan huruf kecil, angka, dan tanda hubung (-), dan panjangnya harus antara 3 dan 31 karakter.
Pilih model kapasitas	Pilih Tanpa server untuk membuat akun dalam mode tanpa server.
Pilih grup sumber daya untuk sumber daya baru	Pilih grup sumber daya tempat Anda membuat aplikasi fungsi di artikel sebelumnya.
Pilih lokasi untuk sumber daya baru	Pilih lokasi geografis untuk menghosting akun Azure Cosmos DB Anda. Gunakan lokasi yang paling dekat dengan Anda atau pengguna Anda untuk mendapatkan akses tercepat ke data.

Setelah akun baru Anda tersedia, pesan akan ditampilkan di area notifikasi.

Membuat database dan kontainer Azure Cosmos DB

Pilih ikon Azure di bilah Aktivitas, perluas Sumber Daya>Azure Cosmos DB, klik kanan (Ctrl+pilih di macOS) akun Anda, dan pilih Buat database....
Berikan informasi berikut pada permintaan:

Prompt Pilihan

Nama database Ketik my-database.

Masukkan ID untuk koleksi Anda Ketik my-container.

Masukkan kunci partisi untuk koleksi tersebut Ketik /id sebagai kunci partisi.
Pilih OK untuk membuat kontainer dan database.

Prompt	Pilihan
Nama database	Ketik `my-database`.
Masukkan ID untuk koleksi Anda	Ketik `my-container`.
Masukkan kunci partisi untuk koleksi tersebut	Ketik `/id` sebagai kunci partisi.

Memperbarui pengaturan aplikasi fungsi Anda

Di artikel mulai cepat sebelumnya, Anda membuat aplikasi fungsi di Azure. Dalam artikel ini, Anda memperbarui aplikasi untuk menulis dokumen JSON ke kontainer Azure Cosmos DB yang telah Anda buat. Untuk menyambungkan ke akun Azure Cosmos DB, Anda harus menambahkan string koneksi ke pengaturan aplikasi Anda. Kemudian unduh pengaturan baru ke file local.settings.json sehingga Anda dapat terhubung ke akun Azure Cosmos DB Anda saat berjalan secara lokal.

Di Visual Studio Code, klik kanan (Ctrl+pilih di macOS) di akun Azure Cosmos DB baru Anda, dan pilih Salin String Koneksi.
Tekan F1 untuk membuka palet perintah, lalu cari dan jalankan perintah Azure Functions: Add New Setting....

Pilih aplikasi fungsi yang Anda buat di artikel sebelumnya. Berikan informasi berikut pada permintaan:

Prompt	Pilihan
Masukkan nama pengaturan aplikasi baru	Ketik `CosmosDbConnectionSetting`.
Masukkan nilai untuk "CosmosDbConnectionSetting"	Tempelkan string koneksi akun Azure Cosmos DB yang Anda salin. Anda juga dapat mengonfigurasi identitas Microsoft Entra sebagai alternatif.

Tindakan ini akan membuat pengaturan aplikasi bernama koneksi CosmosDbConnectionSetting pada aplikasi fungsi Anda di Azure. Sekarang, Anda dapat mengunduh pengaturan ini ke file local.settings.json.

Tekan F1 lagi untuk membuka palet perintah, lalu cari dan jalankan perintah Azure Functions: Download Remote Settings....
Pilih aplikasi fungsi yang Anda buat di artikel sebelumnya. Pilih Ya untuk semua untuk mengganti pengaturan lokal yang ada.

Maka akan terunduh semua pengaturan dari Azure ke proyek lokal Anda, termasuk pengaturan string koneksi baru. Sebagian besar pengaturan yang diunduh tidak digunakan saat berjalan secara lokal.

Mendaftarkan ekstensi pengikatan

Karena Anda menggunakan pengikatan output Azure Cosmos DB, Anda harus menginstal ekstensi pengikatan yang sesuai sebelum Anda menjalankan proyek.

Kecuali untuk pemicu HTTP dan timer, pengikatan diimplementasikan sebagai paket ekstensi. Jalankan perintah dotnet add package berikut di jendela Terminal untuk menambahkan paket ekstensi Azure Cosmos DB ke proyek Anda.

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB

Proyek Anda telah dikonfigurasi untuk menggunakan bundel ekstensi, yang secara otomatis menginstal set paket ekstensi yang telah ditentukan sebelumnya.

Penggunaan bundel ekstensi diaktifkan di file host.json pada akar proyek, yang muncul sebagai berikut:

{
  "version": "2.0",
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[4.*, 5.0.0)"
  },
  "concurrency": {
    "dynamicConcurrencyEnabled": true,
    "snapshotPersistenceEnabled": true
  },
  "extensions": {
    "cosmosDB": {
      "connectionMode": "Gateway"
    }
  }
}

Proyek Anda telah dikonfigurasi untuk menggunakan bundel ekstensi, yang secara otomatis menginstal set paket ekstensi yang telah ditentukan sebelumnya.

Penggunaan bundel ekstensi diaktifkan di file host.json pada akar proyek, yang muncul sebagai berikut:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  } 
}

Sekarang, Anda dapat menambahkan pengikatan output Azure Cosmos DB ke proyek Anda.

Menambahkan pengikatan output

Dalam proyek pustaka kelas C#, pengikatan didefinisikan sebagai atribut pengikatan pada metode fungsi.

Buka file proyek HttpExample.cs dan tambahkan kelas berikut:

public class MultiResponse
{
    [CosmosDBOutput("my-database", "my-container",
        Connection = "CosmosDbConnectionSetting", CreateIfNotExists = true)]
    public MyDocument Document { get; set; }
    public HttpResponseData HttpResponse { get; set; }
}
public class MyDocument {
    public string id { get; set; }
    public string message { get; set; }
}

Kelas MyDocument mendefinisikan objek yang akan ditulis ke database. String koneksi untuk akun penyimpanan diatur oleh properti Connection. Dalam hal ini, Anda dapat mengabaikan Connection karena Anda sudah menggunakan akun penyimpanan default.

Kelas MultiResponse memungkinkan Anda menulis ke koleksi yang ditentukan di Azure Cosmos DB dan memunculkan pesan berhasil HTTP. Karena Anda perlu memunculkan objek MultiResponse, Anda juga perlu memperbarui tanda tangan metode.

Atribut tertentu menentukan nama kontainer dan nama database induknya. String koneksi untuk akun Azure Cosmos DB Anda diatur oleh CosmosDbConnectionSetting.

Atribut pengikatan didefinisikan langsung dalam kode fungsi Anda. Konfigurasi output Azure Cosmos DB menjelaskan bidang yang diperlukan untuk pengikatan output Azure Cosmos DB.

Untuk skenario ini MultiResponse , Anda perlu menambahkan pengikatan extraOutputs output ke fungsi .

app.http('HttpExample', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {

Tambahkan properti berikut ke konfigurasi pengikatan:

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

Atribut pengikatan didefinisikan langsung dalam file function_app.py . Anda menggunakan cosmos_db_output dekorator untuk menambahkan pengikatan output Azure Cosmos DB:

@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
    container_name="my-container", connection="CosmosDbConnectionSetting")

Dalam kode ini, arg_name mengidentifikasi parameter pengikatan yang dirujuk dalam kode Anda, database_name dan container_name merupakan nama database dan koleksi tempat pengikatan menulis, dan connection merupakan nama pengaturan aplikasi yang berisi string koneksi untuk akun Azure Cosmos DB, yang ada dalam CosmosDbConnectionSetting pengaturan dalam file local.settings.json.

Tambahkan kode yang menggunakan pengikatan output

Ganti metode Eksekusi yang ada dengan kode berikut:

[Function("HttpExample")]
public static MultiResponse Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var logger = executionContext.GetLogger("HttpExample");
    logger.LogInformation("C# HTTP trigger function processed a request.");

    var message = "Welcome to Azure Functions!";

    var response = req.CreateResponse(HttpStatusCode.OK);
    response.Headers.Add("Content-Type", "text/plain; charset=utf-8");
    response.WriteString(message);

    // Return a response to both HTTP trigger and Azure Cosmos DB output binding.
    return new MultiResponse()
    {
         Document = new MyDocument
        {
            id = System.Guid.NewGuid().ToString(),
            message = message
        },
        HttpResponse = response
    };
}

Tambahkan kode yang menggunakan extraInputs objek pengikatan output pada context untuk mengirim dokumen JSON ke fungsi pengikatan output bernama, sendToCosmosDb. Tambahkan kode ini sebelum pernyataan return.

context.extraOutputs.set(sendToCosmosDb, {
  // create a random ID
  id:
    new Date().toISOString() + Math.random().toString().substring(2, 10),
  name: name,
});

Pada titik ini, fungsi Anda akan terlihat sebagai berikut:

const { app, output } = require('@azure/functions');

const sendToCosmosDb = output.cosmosDB({
  databaseName: 'my-database',
  containerName: 'my-container',
  createIfNotExists: false,
  connection: 'CosmosDBConnectionString',
});

app.http('HttpExampleToCosmosDB', {
  methods: ['GET', 'POST'],
  extraOutputs: [sendToCosmosDb],
  handler: async (request, context) => {
    try {
      context.log(`Http function processed request for url "${request.url}"`);

      const name = request.query.get('name') || (await request.text());

      if (!name) {
        return { status: 404, body: 'Missing required data' };
      }

      // Output to Database
      context.extraOutputs.set(sendToCosmosDb, {
        // create a random ID
        id:
          new Date().toISOString() + Math.random().toString().substring(2, 10),
        name: name,
      });

      const responseMessage = name
        ? 'Hello, ' +
          name +
          '. This HTTP triggered function executed successfully.'
        : 'This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.';

      // Return to HTTP client
      return { body: responseMessage };
    } catch (error) {
      context.log(`Error: ${error}`);
      return { status: 500, body: 'Internal Server Error' };
    }
  },
});

Sekarang kode ini memunculkan objek MultiResponse yang berisi dokumen dan respons HTTP.

Perbarui HttpExample\function_app.py agar sesuai dengan kode berikut. outputDocument Tambahkan parameter ke definisi fungsi dan outputDocument.set() di if name: bawah pernyataan:

import azure.functions as func
import logging

app = func.FunctionApp()

@app.function_name(name="HttpTrigger1")
@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", container_name="my-container", connection="CosmosDbConnectionSetting")
def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
     logging.info('Python HTTP trigger function processed a request.')
     logging.info('Python Cosmos DB trigger function processed a request.')
     name = req.params.get('name')
     if not name:
        try:
            req_body = req.get_json()
        except ValueError:
            pass
        else:
            name = req_body.get('name')

     if name:
        outputDocument.set(func.Document.from_dict({"id": name}))
        msg.set(name)
        return func.HttpResponse(f"Hello {name}!")
     else:
        return func.HttpResponse(
                    "Please pass a name on the query string or in the request body",
                    status_code=400
                )

Dokumen {"id": "name"} dibuat dalam kumpulan database yang ditentukan dalam pengikatan.

Jalankan fungsi secara lokal

Visual Studio Code terintegrasi dengan alat Azure Functions Core untuk memungkinkan Anda menjalankan proyek ini di komputer pengembangan lokal sebelum Anda menerbitkan ke Azure. Jika Anda belum menginstal Core Tools secara lokal, Anda akan diminta untuk menginstalnya saat pertama kali menjalankan proyek Anda.

Untuk memanggil fungsi, tekan F5 untuk memulai proyek aplikasi fungsi. Panel Terminal menampilkan output dari Core Tools. Aplikasi Anda dimulai di panel Terminal. Anda dapat melihat titik akhir URL dari fungsi yang dipicu HTTP berjalan secara lokal.

Jika Anda belum menginstal Core Tools, pilih Instal untuk menginstal Core Tools saat diminta untuk melakukannya.
Jika Anda mengalami masalah saat menjalankan fungsi di Windows, pastikan bahwa terminal default untuk Visual Studio Code tidak diatur ke WSL Bash.
Saat Core Tools sedang berjalan, buka area Azure: Functions. Pada bagian Fungsi, luaskan Proyek Lokal>Fungsi. Klik kanan (Windows) atau Ctrl - klik (macOS) fungsi HttpExample dan pilih Jalankan Fungsi Sekarang....
Di Masukkan isi permintaan, tekan Enter untuk mengirim pesan permintaan ke fungsi Anda.
Saat fungsi dijalankan secara lokal dan mengembalikan respons, pemberitahuan akan dimunculkan dalam Visual Studio Code. Informasi tentang eksekusi fungsi ditampilkan di panel Terminal.
Tekan Ctrl + C untuk menghentikan Azure Functions Core Tools dan putuskan sambungan debugger.

Jalankan fungsi secara lokal

Seperti pada artikel sebelumnya, tekan F5 untuk memulai proyek aplikasi fungsi dan Core Tools.
Dengan menjalankan Core Tools, buka area Azure: Functions. Pada bagian Fungsi, luaskan Proyek Lokal>Fungsi. Klik kanan (klik Ctrl di Mac) fungsi HttpExample dan pilih Jalankan Fungsi Sekarang....
Di Masukkan isi permintaan Anda melihat nilai isi pesan permintaan { "name": "Azure" }. Tekan Masukkan untuk mengirim pesan permintaan ini ke fungsi Anda.
Setelah respons dikembalikan, tekan Ctrl + C untuk menghentikan Core Tools.

Memverifikasi bahwa dokumen JSON telah dibuat

Di portal Microsoft Azure, kembali ke akun Azure Cosmos DB Anda dan pilih Data Explorer.
Luaskan database dan kontainer Anda, dan pilih Item untuk mencantumkan dokumen yang dibuat di kontainer Anda.
Verifikasi bahwa dokumen JSON baru telah dibuat oleh pengikatan output.

Menyebarkan ulang dan memverifikasi aplikasi yang diperbarui

Di Visual Studio Code, tekan F1 untuk membuka palet perintah. Di palet perintah, cari dan pilih Azure Functions: Deploy to function app....
Pilih aplikasi fungsi yang Anda buat di artikel pertama. Karena Anda melakukan penyebaran kembali proyek Anda ke aplikasi yang sama, pilih Sebarkan untuk menghilangkan peringatan tentang mengganti file.
Setelah penyebaran selesai, Anda dapat kembali menggunakan fitur Jalankan Fungsi Sekarang... untuk memicu fungsi di Azure.
Sekali lagi periksa dokumen yang dibuat di kontainer Azure Cosmos DB Anda untuk memverifikasi bahwa pengikatan output kembali menghasilkan dokumen JSON baru.

Membersihkan sumber daya

Di Azure, sumber daya merujuk ke aplikasi fungsi, fungsi, akun penyimpanan, dan sebagainya. Sumber daya tersebut dikelompokkan ke dalamgrup sumber daya, dan Anda dapat menghapus semuanya dalam grup dengan menghapus grup.

Anda perlu membuat sumber daya untuk menyelesaikan mulai cepat ini. Anda akan ditagihkan untuk sumber daya ini, tergantung pada status akun dan harga layanan Anda. Jika Anda tidak memerlukan sumber daya lagi, berikut cara menghapusnya:

Di Visual Studio Code, tekan F1 untuk membuka palet perintah. Di palet perintah, cari dan pilih Azure: Open in portal.
Pilih aplikasi fungsi Anda dan tekan Enter. Halaman aplikasi fungsi terbuka di portal Azure.
Di tab Ringkasan, pilih tautan bernama di samping Grup sumber daya.
Di halaman Grup sumber daya, tinjau daftar sumber daya yang disertakan, dan pastikan sumber daya tersebut adalah sumber daya yang ingin Anda hapus.
Pilih Hapus grup sumber daya, dan ikuti instruksinya.

Penghapusan mungkin perlu waktu beberapa menit. Setelah selesai, pemberitahuan akan muncul selama beberapa detik. Anda juga dapat memilih ikon bel di bagian atas halaman untuk melihat pemberitahuan.

Langkah berikutnya

Anda telah memperbarui fungsi pemicu HTTP Anda untuk menulis dokumen JSON ke kontainer Azure Cosmos DB. Sekarang Anda bisa mempelajari selengkapnya tentang mengembangkan Azure Functions menggunakan Visual Studio Code:

Bagikan melalui

Menyambungkan Azure Functions ke Azure Cosmos DB menggunakan Visual Studio Code

Mengkonfigurasikan lingkungan Anda

Membuat akun Azure Cosmos DB

Membuat database dan kontainer Azure Cosmos DB

Memperbarui pengaturan aplikasi fungsi Anda

Mendaftarkan ekstensi pengikatan

Menambahkan pengikatan output

Tambahkan kode yang menggunakan pengikatan output

Jalankan fungsi secara lokal

Jalankan fungsi secara lokal

Memverifikasi bahwa dokumen JSON telah dibuat

Menyebarkan ulang dan memverifikasi aplikasi yang diperbarui

Membersihkan sumber daya

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: