Buat API tanpa server di Visual Studio menggunakan integrasi Azure Functions dan API Management

Artikel
06/01/2023

REST API sering dijelaskan menggunakan definisi OpenAPI. File ini berisi informasi tentang operasi yang tersedia dalam API dan cara data permintaan dan respons untuk API seharusnya disusun.

Dalam tutorial ini, Anda akan mempelajari cara:

Membuat proyek fungsi tanpa server di Visual Studio
Tes API fungsi secara lokal menggunakan fungsionalitas OpenAPI bawaan
Publikasikan proyek ke aplikasi fungsi di Azure dengan integrasi API Management
Dapatkan kunci akses untuk fungsi dan atur di API Management
Unduh file definisi OpenAPI

Fungsi tanpa server yang Anda buat menyediakan API yang memungkinkan Anda menentukan apakah perbaikan darurat pada turbin angin hemat biaya. Karena aplikasi fungsi dan instans API Management yang Anda buat menggunakan paket konsumsi, biaya yang Anda keluarkan untuk menyelesaikan tutorial ini tidak besar.

Catatan

Integrasi OpenAPI dan API Management yang ditampilkan dalam artikel ini saat ini hanya didukung untuk fungsi pustaka kelas C# dalam proses. Proses pekerja terisolasi Fungsi pustaka kelas C# dan semua runtime bahasa lainnya harus menggunakan integrasi Azure API Management dari portal.

Prasyarat

Visual Studio 2022. Pastikan Anda memilih beban kerja pengembangan Azure selama penginstalan.
Langganan Azure yang aktif, buat akun gratis sebelum memulai.

Buat proyek Functions

Templat proyek Azure Functions di Visual Studio membuat proyek yang bisa Anda terbitkan ke aplikasi fungsi di Azure. Anda juga akan membuat fungsi yang dipicu HTTP yang mendukung pembuatan file definisi OpenAPI (sebelumnya file Swagger).

Dari menu Visual Studio, pilih File>Proyek>Baru.
Di Buat proyek baru, masukkan fungsi di kotak pencarian, pilih templat Azure Functions, lalu pilih Berikutnya.
Di Konfigurasikan proyek baru Anda, masukkan nama Proyek untuk proyek seperti TurbineRepair, lalu pilih Buat.

Untuk pengaturan Buat aplikasi Azure Functions baru, gunakan nilai dalam tabel berikut:

Pengaturan	Nilai	Deskripsi
Pekerja fungsi	.NET 6	Nilai ini membuat proyek fungsi yang berjalan dalam proses pada versi 4.x dari runtime Azure Functions, yang diperlukan untuk pembuatan file OpenAPI.
Templat fungsi	Pemicu HTTP dengan OpenAPI	Nilai ini membuat fungsi yang dipicu oleh permintaan HTTP, dengan kemampuan untuk menghasilkan file definisi OpenAPI.
Gunakan Azurite untuk akun penyimpanan runtime bahasa umum (AzureWebJobsStorage)	Dipilih	Anda dapat menggunakan emulator untuk pengembangan lokal fungsi pemicu HTTP. Karena aplikasi fungsi di Azure memerlukan akun penyimpanan, aplikasi ditetapkan atau dibuat saat Anda memublikasikan proyek Anda ke Azure.
Tingkat otorisasi	Fungsi	Saat berjalan di Azure, klien harus menyediakan kunci saat mengakses titik akhir. Untuk informasi selengkapnya tentang kunci dan otorisasi, lihat tombol akses fungsi.

Pengaturan proyek Azure Functions

Pilih Buat untuk membuat proyek fungsi dan fungsi pemicu HTTP, dengan dukungan untuk OpenAPI.

Visual Studio membuat proyek dan kelas yang bernama Function1 yang berisi kode boilerplate untuk jenis fungsi pemicu HTTP. Selanjutnya, Anda mengganti kode template fungsi ini dengan kode yang dikustomisasi sendiri.

Memperbarui kode fungsi

Fungsi ini menggunakan pemicu HTTP yang mengambil dua parameter:

Nama parameter	Deskripsi
jam	Perkiraan waktu untuk melakukan perbaikan turbin, hingga satu jam penuh terdekat.
kapasitas	Kapasitas turbin, dalam kilowatt.

Fungsi ini kemudian menghitung jumlah biaya perbaikan, dan jumlah pendapatan yang bisa dibuat turbin dalam periode 24 jam. Parameter disediakan baik dalam string kueri atau dalam muatan permintaan POST.

Dalam file function1.cs project, ganti konten kode library kelas yang dihasilkan dengan kode berikut:

using System;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;

namespace TurbineRepair
{
    public static class Turbines
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        [FunctionName("TurbineRepair")]
        [OpenApiOperation(operationId: "Run")]
        [OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
        [OpenApiRequestBody("application/json", typeof(RequestBodyModel), 
            Description = "JSON request body containing { hours, capacity}")]
        [OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
            Description = "The OK response message containing a JSON result.")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
            ILogger log)
        {
            // Get request body data.
            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            int? capacity = data?.capacity;
            int? hours = data?.hours;

            // Return bad request if capacity or hours are not passed in
            if (capacity == null || hours == null)
            {
                return new BadRequestObjectResult("Please pass capacity and hours in the request body");
            }
            // Formulas to calculate revenue and cost
            double? revenueOpportunity = capacity * revenuePerkW * 24;
            double? costToFix = (hours * technicianCost) + turbineCost;
            string repairTurbine;

            if (revenueOpportunity > costToFix)
            {
                repairTurbine = "Yes";
            }
            else
            {
                repairTurbine = "No";
            };

            return (ActionResult)new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
    }
    public class RequestBodyModel
    {
        public int Hours { get; set; }
        public int Capacity { get; set; } 
    }
}

Kode fungsi ini mengembalikan pesan Yes atau No untuk menunjukkan apakah perbaikan darurat hemat biaya. Ini juga mengembalikan peluang pendapatan yang diwakili turbin dan biaya untuk memperbaiki turbin.

Jalankan dan verifikasi API secara lokal

Saat Anda menjalankan fungsi, titik akhir OpenAPI memudahkan untuk mencoba fungsi secara lokal menggunakan halaman yang dihasilkan. Anda tidak perlu menyediakan tombol akses fungsi saat berjalan secara lokal.

Tekan F5 untuk memulai proyek. Saat runtime Functions dimulai secara lokal, sekumpulan titik akhir OpenAPI dan Swagger diperlihatkan dalam output, bersama dengan titik akhir fungsi.
Di browser Anda, buka titik akhir RenderSwaggerUI, yang seharusnya terlihat seperti http://localhost:7071/api/swagger/ui. Halaman dirender, berdasarkan definisi OpenAPI Anda.
Pilih POST>Cobalah, masukkan nilai untuk hours dan capacity baik sebagai parameter kueri atau di isi permintaan JSON, dan pilih Jalankan.
Saat Anda memasukkan nilai bilangan bulat seperti 6 untuk hours dan 2500 untuk capacity, Anda mendapatkan respons JSON yang terlihat seperti contoh berikut:

Sekarang Anda memiliki fungsi yang menentukan efektivitas biaya perbaikan darurat. Selanjutnya, Anda menerbitkan definisi proyek dan API ke Azure.

Menerbitkan proyek ke Azure

Anda harus memiliki aplikasi fungsi di langganan Azure Anda sebelum dapat menerbitkan proyek. Penerbitan Visual Studio membuat aplikasi fungsi saat pertama kali menerbitkan proyek Anda. Ini juga dapat membuat instans API Management yang terintegrasi dengan aplikasi fungsi Anda untuk mengekspos API TurbineRepair.

Di Penjelajah Solusi, klik kanan pada proyek, pilih Terbitkan dan di Target, pilih Azure lalu Berikutnya.
Untuk Target tertentu, pilih Azure Function App (Windows) untuk membuat aplikasi fungsi yang berjalan di Windows, lalu pilih Berikutnya.
Di Instans Function, pilih + Buat Azure Function baru... .

Buat instans baru menggunakan nilai yang ditentukan dalam tabel berikut:

Pengaturan	Nilai	Deskripsi
Nama	Nama unik global	Nama yang mengidentifikasi secara unik aplikasi fungsi baru Anda. Terima nama ini atau masukkan nama baru. Karakter yang valid adalah: `a-z`, `0-9`, dan `-`.
Langganan	Langganan Anda	Langganan Azure yang akan digunakan. Terima langganan ini atau pilih yang baru dari daftar menurun.
Grup sumber daya	Nama grup sumber daya Anda	Grup sumber daya untuk membuat aplikasi fungsi Anda. Pilih grup sumber daya yang ada dari daftar menurun atau pilih Baru untuk membuat grup sumber daya baru.
Jenis Paket	Consumption	Saat Anda menerbitkan proyek Anda ke aplikasi fungsi yang berjalan dalam Paket konsumsi, Anda hanya membayar untuk menjalankan aplikasi fungsi Anda. Paket hosting lain dikenakan biaya yang lebih tinggi.
Lokasi	Lokasi layanan	Pilih Lokasi di wilayah dekat Anda atau dekat layanan lain yang diakses fungsi Anda.
Azure Storage	Akun penyimpanan serba guna	Akun Azure Storage diperlukan oleh runtime Fungsi. Pilih Baru untuk mengonfigurasi akun penyimpanan serba guna. Anda juga dapat memilih akun yang ada yang memenuhi persyaratan akun penyimpanan.

Membuat aplikasi fungsi baru di Azure dengan Storage

Pilih Buat untuk membuat aplikasi fungsi dan sumber daya terkait di Azure. Status pembuatan sumber daya ditampilkan di kiri bawah jendela.
Kembali ke Instans fungsi, pastikan Menjalankan dari file paket dicentang. Aplikasi fungsi diterapkan menggunakan Zip Deploy dengan mode Run-From-Package diaktifkan. Metode penyebaran ini direkomendasikan untuk proyek fungsi Anda, karena menghasilkan performa yang lebih baik.
Pilih Berikutnya, dan di halaman API Management, juga pilih + Buat API Management API.

Buat API di API Management dengan menggunakan nilai pada tabel berikut:

Pengaturan	Nilai	Deskripsi
Nama API	TurbineRepair	Nama untuk API.
Nama langganan	Langganan Anda	Langganan Azure yang akan digunakan. Terima langganan ini atau pilih langganan baru dari daftar drop-down.
Grup Sumber Daya	Nama grup sumber daya Anda	Pilih grup sumber daya yang sama dengan aplikasi fungsi Anda dari daftar drop-down.
Layanan API Management	Instans baru	Pilih Baru untuk membuat instance API Management baru di tingkat tanpa server.

Buat instans API Management dengan API

Pilih Buat untuk membuat instans API Management dengan API TurbineRepair dari integrasi fungsi.
pilih Selesai, verifikasi halaman Terbitkan mengatakan Siap untuk menerbitkan, lalu pilih Terbitkan untuk menerapkan paket yang berisi file proyek Anda ke aplikasi fungsi baru Anda di Azure.

Setelah penyebaran selesai, URL akar aplikasi fungsi di Azure diperlihatkan di tab Terbitkan.

Dapatkan kunci akses fungsi

Di tab Terbitkan, pilih elipsis ( ... ) di samping Hosting dan pilih Buka di portal Microsoft Azure. Aplikasi fungsi yang Anda buat dibuka di portal Microsoft Azure di browser default Anda.
Di bawah Functions, pilih Functions>TurbineRepair lalu pilih kunci Fungsi.
Di bawah kunci Fungsi, pilih default dan salin nilai. Anda sekarang dapat mengatur kunci ini di API Management sehingga dapat mengakses titik akhir fungsi.

Konfigurasikan API Management

Di tab Terbitkan, pilih elipsis ( ... ) di samping Hosting dan pilih Buka API di portal Microsoft Azure. Instans API Management yang Anda buat dibuka di portal Microsoft Azure di browser default Anda. Instans API Management ini sudah ditautkan ke aplikasi fungsi Anda.
Di bawah API, pilih Dokumen OpenAPI di Azure Functions>POST Jalankan, lalu di bawah Pemrosesan masuk pilih Tambahkan kebijakan.
Dalam pemrosesan masuk, pilih Atur parameter kueri, ketik code untuk Nama, pilih +Value, tempel di kunci fungsi yang disalin, dan pilih Simpan. API Management menyertakan kunci fungsi saat melewati panggilan ke titik akhir fungsi.

Setelah kunci fungsi diatur, Anda dapat memanggil API untuk memverifikasi bahwa kunci tersebut berfungsi saat dihosting di Azure.

Memverifikasi API di Azure

Di API, pilih tab Uji lalu POST Run, masukkan kode berikut di Isi permintaan>Raw, dan pilih Kirim:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Seperti sebelumnya, Anda juga bisa menyediakan nilai yang sama dengan parameter kueri.
Pilih Kirim, lalu lihat respons HTTP untuk memverifikasi hasil yang sama dikembalikan dari API.

Mengunduh definisi OpenAPI

Jika API berfungsi seperti yang diharapkan, Anda dapat mengunduh definisi OpenAPI.

1. Di bawah API, pilih Buka Dokumen API pada Azure Functions, pilih elipsis (...), dan pilih Ekspor.
Pilih sarana ekspor API, termasuk file OpenAPI dalam berbagai format. Anda juga dapat mengekspor API dari Azure API Management ke Power Platform.

Membersihkan sumber daya

Dalam langkah-langkah sebelumnya, Anda membuat sumber daya Azure dalam grup sumber daya. Jika Anda tidak berharap membutuhkan sumber daya ini di masa mendatang, Anda dapat menghapusnya dengan menghapus grup sumber daya.

Pada beranda portal Microsoft Azure atau halaman Beranda, pilih Grup sumber daya. Lalu, pada halaman Grup sumber daya, pilih grup yang Anda buat.

Pada halaman myResourceGroup, pastikan sumber daya yang tercantum adalah sumber daya yang ingin Anda hapus.

Pilih Hapus grup sumber daya, ketik nama grup Anda di kotak teks untuk mengonfirmasi, lalu pilih Hapus.

Langkah berikutnya

Anda telah menggunakan Visual Studio 2022 untuk membuat fungsi yang mendokumentasikan sendiri karena Ekstensi OpenAPI dan terintegrasi dengan API Management. Anda sekarang dapat memperbaiki definisi dalam API Management di portal. Anda juga dapat mempelajari lebih lanjut tentang API Management.

Edit definisi OpenAPI di API Management