Azure İşlevleri ve API Management tümleştirmesi kullanarak Visual Studio'da sunucusuz API'ler oluşturma

Makale
08/08/2024

REST API'leri genellikle bir OpenAPI tanımı (eski adıyla Swagger) dosyası kullanılarak açıklanır. Bu dosya, BIR API'deki işlemler ve API için istek ve yanıt verilerinin nasıl yapılandırılması gerektiği hakkında bilgi içerir.

Bu öğreticide aşağıdakilerin nasıl yapılacağını öğreneceksiniz:

Visual Studio'da kod projesi oluşturma
OpenAPI uzantısını yükleme
OpenAPI tanımlarını içeren bir HTTP tetikleyici uç noktası ekleme
Yerleşik OpenAPI işlevselliğini kullanarak işlev API'lerini yerel olarak test edin
Azure'da bir işlev uygulamasına proje yayımlama
API Management tümleştirmesini etkinleştirme
OpenAPI tanım dosyasını indirme

Oluşturduğunuz sunucusuz işlev, rüzgar türbininde acil durum onarımının uygun maliyetli olup olmadığını belirlemenizi sağlayan bir API sağlar. Tüketim katmanında hem işlev uygulamasını hem de API Management örneğini oluşturduğunuz için bu öğreticiyi tamamlama maliyetiniz çok düşüktür.

Önkoşullar

Visual Studio 2022. Yükleme sırasında Azure geliştirme iş yükünü seçtiğinizden emin olun.
Etkin bir Azure aboneliği, başlamadan önce ücretsiz bir hesap oluşturun.

Kod projesini oluşturma

Visual Studio'daki Azure İşlevleri proje şablonu, Azure'daki bir işlev uygulamasına yayımlayabileceğiniz bir proje oluşturur. OpenAPI tanım dosyasını (eski adıyla Swagger dosyası) oluşturmayı destekleyen bir şablondan HTTP ile tetiklenen bir işlev de oluşturacaksınız.

Visual Studio menüsünden Dosya>Yeni Proje'yi> seçin.
Yeni proje oluştur'da, arama kutusuna işlevler yazın, Azure İşlevleri şablonunu seçin ve ardından İleri'yi seçin.
Yeni projenizi yapılandırın bölümünde, projeniz için gibi TurbineRepairbir Proje adı girin ve Oluştur'u seçin.
Yeni Azure İşlevleri uygulaması oluştur ayarları için, seçtiğiniz işlem modeline bağlı olan İşlevler çalışanı için şu seçeneklerden birini belirleyin:
- Yalıtılmış çalışan modeli
- İşlemde
.NET 8.0 Yalıtılmış (Uzun Süreli Destek): C# işlevleriniz yalıtılmış çalışan modelinde çalışır ve bu önerilir. Daha fazla bilgi için yalıtılmış çalışan modeli kılavuzuna bakın.

Önemli

İşlem içi model desteği 10 Kasım 2026'da sona erecektir. Tam destek için uygulamalarınızı yalıtılmış çalışan modeline geçirmenizi kesinlikle öneririz.

.NET 8.0 (Uzun Vadeli Destek): C# işlevleriniz kullanımdan kaldırılacak işlem içi modelde çalışır. Daha fazla bilgi edinmek için işlem içi model kılavuzuna bakın.

Diğer seçenekler için aşağıdaki tabloda yer alan değerleri kullanın:

Ayar	Value	Açıklama
İşlev şablonu	Boş	Bu, tetikleyicisi olmayan bir proje oluşturur ve daha sonra eklediğinizde HTTP ile tetiklenen işlevin adı üzerinde daha fazla denetim sağlar.
Çalışma zamanı depolama hesabı için Azurite kullanma (AzureWebJobsStorage)	Seçilmiş	HTTP tetikleyici işlevlerinin yerel olarak geliştirilmesi için öykünücüyü kullanabilirsiniz. Azure'daki bir işlev uygulaması için depolama hesabı gerektiğinden, projenizi Azure'da yayımladığınızda bir uygulama atanır veya oluşturulur.
Yetkilendirme düzeyi	İşlev	Azure'da çalışırken istemcilerin uç noktaya erişirken bir anahtar sağlaması gerekir. Daha fazla bilgi için bkz . Yetkilendirme düzeyi.

İşlev projesini oluşturmak için Oluştur'u seçin.

Ardından, uygulamanızda API uç noktalarının bulunabilirliğini sağlayan Azure İşlevleri için OpenAPI uzantısını yükleyerek projeyi güncelleştireceksiniz.

OpenAPI uzantısını yükleme

OpenAPI uzantısını yüklemek için:

Araçlar menüsünde NuGet Paket Yöneticisi> Paket Yöneticisi Konsolu'nu seçin.
Konsolunda aşağıdaki Install-Package komutunu çalıştırarak OpenAPI uzantısını yükleyin:
- Yalıtılmış çalışan modeli
- İşlem içi model
```
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
```
.NET sürümünüz temelinde belirli bir sürümü güncelleştirmeniz gerekebilir.
```
NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi -Version 1.5.1
```
.NET sürümünüz temelinde belirli bir sürümü güncelleştirmeniz gerekebilir.

Artık HTTP uç nokta işlevinizi ekleyebilirsiniz.

HTTP uç noktası işlevi ekleme

C# sınıf kitaplığında, işlev tarafından kullanılan bağlamalar koda öznitelikler uygulanarak tanımlanır. HTTP tetikleyicisi ile işlev oluşturmak için:

Çözüm Gezgini'da proje düğümünüzü sağ tıklatın ve Yeni Azure İşlevi Ekle'yi>seçin.
Sınıf için Turbine.cs girin ve Ekle'yi seçin.
Http tetikleyici şablonunu seçin, Yetkilendirme düzeyini İşlev olarak ayarlayın ve ardından Ekle'yi seçin. Projenize HTTP tetikleyicisi olan yeni bir işlev uç noktasını tanımlayan bir Turbine.cs kod dosyası eklenir.

Artık HTTP tetikleyicisi şablon kodunu Türbin işlevi uç noktasını uygulayan kodla ve uç noktayı tanımlamak için OpenAPI kullanan özniteliklerle değiştirebilirsiniz.

İşlev kodunu güncelleştirme

İşlev, iki parametre alan bir HTTP tetikleyicisi kullanır:

Parametre adı	Açıklama
hours	Türbin onarımı için en yakın tam saate kadar tahmini süre.
kapasite	Türbinin kapasitesi, kilowatt cinsinden.

İşlev daha sonra bir onarım maliyetini ve türbinin 24 saatlik bir süre içinde ne kadar gelir elde edebileceğini hesaplar. Parametreler sorgu dizesinde veya POST isteğinin yükünde sağlanır.

Turbine.cs proje dosyasında, HTTP tetikleyici şablonundan oluşturulan sınıfın içeriğini işlem modelinize bağlı olarak aşağıdaki kodla değiştirin:

Yalıtılmış çalışan modeli
İşlem içi model

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
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;
using System.Net;

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

        private readonly ILogger<Turbine> _logger;

        public Turbine(ILogger<Turbine> logger)
        {
            _logger = logger;
        }

        [Function("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 new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
        public class RequestBodyModel
        {
            public int Hours { get; set; }
            public int Capacity { get; set; }
        }
    }
}

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 Turbine
    {
        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; } 
    }
}

Bu işlev kodu, acil durum onarımının Yes uygun maliyetli olup olmadığını belirten veya No iletisini döndürür. Ayrıca türbinin temsil ettiği gelir fırsatını ve türbini düzeltme maliyetini döndürür.

API'yi yerel olarak çalıştırma ve doğrulama

İşlevi çalıştırdığınızda, OpenAPI uç noktaları oluşturulan bir sayfayı kullanarak işlevi yerel olarak denemeyi kolaylaştırır. Yerel olarak çalışırken işlev erişim anahtarları sağlamanız gerekmez.

Projeyi başlatmak için F5 tuşuna basın. İşlevler çalışma zamanı yerel olarak başlatıldığında, çıkışta işlev uç noktasıyla birlikte bir dizi OpenAPI ve Swagger uç noktası gösterilir.
Tarayıcınızda, gibi http://localhost:7071/api/swagger/uigörünmesi gereken RenderSwaggerUI uç noktasını açın. OpenAPI tanımlarınıza göre bir sayfa işlenir.
POST>Deneyin'i seçin, sorgu parametreleri olarak veya capacity JSON isteği gövdesine değerlerini hours girin ve Yürüt'e tıklayın.
için 6 ve için hours capacity2500 gibi tamsayı değerleri girdiğinizde, aşağıdaki örneğe benzer bir JSON yanıtı alırsınız:

Acil onarımların maliyet açısından uygunluğunu belirleyen bir işleviniz oldu. Ardından proje ve API tanımlarınızı Azure'da yayımlayabilirsiniz.

Projeyi Azure'da yayımlama

Projenizi yayımlayabilmeniz için önce Azure aboneliğinizde bir işlev uygulaması olması gerekir. Visual Studio yayımlama, projenizi ilk kez yayımladığınızda bir işlev uygulaması oluşturur. Ayrıca TurbineRepair API'sini kullanıma sunma amacıyla işlev uygulamanızla tümleşen bir API Management örneği oluşturabilir.

Çözüm Gezgini'da projeye sağ tıklayın ve Yayımla'yı seçin ve Hedef'te Azure'ı ve ardından İleri'yi seçin.
Belirli hedef için Azure İşlev Uygulaması (Windows) öğesini seçerek Windows üzerinde çalışan bir işlev uygulaması oluşturun ve ardından İleri'yi seçin.
İşlev Örneği'nde + Yeni Bir Azure İşlevi Oluştur... öğesini seçin.

Aşağıdaki tabloda belirtilen değerleri kullanarak yeni bir örnek oluşturun:

Ayar	Value	Açıklama
Adı	Genel olarak benzersiz bir ad	Yeni işlev uygulamanızı benzersiz şekilde tanımlayan ad. Bu adı kabul edin veya yeni bir ad girin. Geçerli karakterler şunlardır: `a-z`, `0-9`ve `-`.
Abonelik	Aboneliğiniz	Kullanılacak Azure aboneliği. Bu aboneliği kabul edin veya açılan listeden yeni bir abonelik seçin.
Kaynak grubu	Kaynak grubunuzun adı	İşlev uygulamanızın oluşturulacağı kaynak grubu. Açılan listeden mevcut bir kaynak grubunu seçin veya yeni bir kaynak grubu oluşturmak için Yeni'yi seçin.
Plan Türü	Tüketim	Projenizi Tüketim planında çalışan bir işlev uygulamasına yayımladığınızda, yalnızca işlev uygulamanızın yürütülmesi için ödeme alırsınız. Diğer barındırma planları daha yüksek maliyetlere neden olur.
Konum	Hizmetin konumu	Size yakın bir bölgede veya işlevlerinizin eriştirileceği diğer hizmetlerde bir Konum seçin.
Azure Depolama	Genel amaçlı depolama hesabı	İşlevler çalışma zamanı için bir Azure Depolama hesabı gereklidir. Genel amaçlı bir depolama hesabı yapılandırmak için Yeni'yi seçin. Depolama hesabı gereksinimlerini karşılayan mevcut bir hesabı da seçebilirsiniz.

Depolama ile Azure'da yeni işlev uygulaması oluşturma

Azure'da bir işlev uygulaması ve ilgili kaynakları oluşturmak için Oluştur'u seçin. Kaynak oluşturma durumu pencerenin sol alt kısmında gösterilir.
İşlevler örneğine döndüğünüzde Paket dosyasından çalıştır seçeneğinin işaretli olduğundan emin olun. İşlev uygulamanız, Paketten Çalıştır modu etkinken Zip Dağıtımı kullanılarak dağıtılır. Bu dağıtım yöntemi, daha iyi performansa neden olduğundan işlev projeniz için önerilir.
İleri'yi seçin ve API Management sayfasında + API Management API'sini oluştur'u da seçin.

Aşağıdaki tabloda yer alan değerleri kullanarak API Management'ta bir API oluşturun:

Ayar	Value	Açıklama
API adı	TürbinRepair	API'nin adı.
Abonelik adı	Aboneliğiniz	Kullanılacak Azure aboneliği. Bu aboneliği kabul edin veya açılan listeden yeni bir abonelik seçin.
Kaynak grubu	Kaynak grubunuzun adı	Açılan listeden işlev uygulamanızla aynı kaynak grubunu seçin.
API Management hizmeti	Yeni örnek	Sunucusuz katmanda aynı konumda yeni bir API Management örneği oluşturmak için Yeni'yi seçin. Örneği oluşturmak için Tamam'ı seçin.

API ile API Management örneği oluşturma

İşlev tümleştirmesinden TurbineRepair API'siyle API Management örneği oluşturmak için Oluştur'u seçin.
Son'u seçin ve yayımlama profili oluşturma işlemi tamamlandıktan sonra Kapat'ı seçin.
Yayımla sayfasında Artık Yayımlamaya hazır ifadesinin yer aldığı doğrulayın ve ardından Yayımla'yı seçerek proje dosyalarınızı içeren paketi Azure'daki yeni işlev uygulamanıza dağıtın.

Dağıtım tamamlandıktan sonra, Azure'daki işlev uygulamasının kök URL'si Yayımla sekmesinde gösterilir.

İşlev erişim anahtarını alma

Yayımla sekmesinde Barındırma'nın yanındaki üç noktayı (...) ve Ardından Azure portalında aç'ı seçin. Oluşturduğunuz işlev uygulaması azure portalında varsayılan tarayıcınızda açılır.
Genel Bakış sayfasındaki İşlevler'in altında Türbin'i ve >ardından İşlev anahtarları'nı seçin.
İşlev tuşları'nın altında, varsayılan anahtarın yanındaki panoya kopyala simgesini seçin. Artık API Management'ta kopyaladığınız bu anahtarı işlev uç noktasına erişebilmesi için ayarlayabilirsiniz.

API Management'ı yapılandırma

İşlev uygulaması sayfasında API'yi genişletin ve API Management'ı seçin.
İşlev uygulaması henüz yeni API Management örneğine bağlı değilse API Management'ın altında api'yi seçin, Azure İşlevleri API>OpenAPI Belgesi'ni seçin, İşlevleri içeri aktar seçeneğinin işaretli olduğundan emin olun ve API'yi bağla'yı seçin. İçeri aktarma için yalnızca TurbineRepair'in seçildiğinden emin olun ve ardından Seç'i seçin.
Sayfanın üst kısmındaki API Management'a git'i seçin ve API Management örneğinde API'leri genişletin.
API'ler Tüm API'ler'in> altında, Azure İşlevleri> POST Çalıştırmasında OpenAPI Belgesi'ni ve ardından Gelen işleme'nin altında İlke>Ekle Sorgu parametrelerini ayarla'yı seçin.
Gelen işleme'nin altında, Sorgu parametrelerini ayarla alanına Ad yazın code , +Değer'i seçin, kopyalanan işlev anahtarını yapıştırın ve Kaydet'i seçin. API Management, çağrıları işlev uç noktasına geçirirken işlev anahtarını içerir.

artık işlev anahtarı ayarlandıysa, API uç noktasını çağırarak turbine Azure'da barındırıldığında çalıştığını doğrulayabilirsiniz.

Azure'da API'yi doğrulama

API'de Test sekmesini ve ardından POST Run'ı seçin, İstek gövdesi>Ham'a aşağıdaki kodu girin ve Gönder'i seçin:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Daha önce olduğu gibi sorgu parametreleriyle aynı değerleri de sağlayabilirsiniz.
Gönder'i seçin ve ardından AYNı sonuçların API'den döndürüldüklerinden emin olmak için HTTP yanıtını görüntüleyin.

OpenAPI tanımını indirme

API'niz beklendiği gibi çalışıyorsa, API Management'tan yeni barındırılan API'ler için OpenAPI tanımını indirebilirsiniz.

1. API'ler'in altında Azure İşlevleri OpenAPI Belgesi'ni seçin, üç noktayı (...) ve dışarı aktar'ı seçin.
Çeşitli biçimlerdeki OpenAPI dosyaları da dahil olmak üzere API dışarı aktarma araçlarını seçin. Api'leri Azure API Management'tan Power Platform'a da aktarabilirsiniz.

Kaynakları temizleme

Önceki adımlarda, bir kaynak grubunda Azure kaynakları oluşturdunuz. İleride bu kaynaklara ihtiyaç duymayacağınızı düşünüyorsanız kaynakları silmek için kaynak grubunu silebilirsiniz.

Azure portalı menüsünden veya Giriş sayfasında Kaynak grupları'nı seçin. Ardından Kaynak grupları sayfasında oluşturduğunuz grubu seçin.

myResourceGroup sayfasında, silmek istediğiniz kaynakların listelenmiş kaynaklar olduğundan emin olun.

Kaynak grubunu sil'i seçin, onaylamak için metin kutusuna grubunuzun adını yazın ve sil'i seçin.

Sonraki adımlar

OpenAPI Uzantısı nedeniyle kendi kendine belgeleyen ve API Management ile tümleşik bir işlev oluşturmak için Visual Studio 2022'yi kullandınız. Artık tanımı portaldaki API Management'ta geliştirebilirsiniz. AYRıCA API Management hakkında daha fazla bilgi edinebilirsiniz.

API Management'ta OpenAPI tanımını düzenleme

Aracılığıyla paylaş