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

Makale
06/01/2023

REST API'leri genellikle OpenAPI tanımı 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 şunların nasıl yapıldığını öğreneceksiniz:

Visual Studio'da sunucusuz işlev projesi oluşturma
Yerleşik OpenAPI işlevselliğini kullanarak işlev API'lerini yerel olarak test edin
API Management tümleştirmesi ile projeyi Azure'da bir işlev uygulamasına yayımlama
İşlevin erişim anahtarını alın ve API Management
OpenAPI tanım dosyasını indirme

Oluşturduğunuz sunucusuz işlev, rüzgar türbininde acil onarımın uygun maliyetli olup olmadığını belirlemenizi sağlayan bir API sağlar. Oluşturduğunuz işlev uygulaması ve API Management örneği kullanım planlarını kullandığından, bu öğreticiyi tamamlama maliyetiniz çok düşüktür.

Not

Bu makalede sunulan OpenAPI ve API Management tümleştirmesi şu anda yalnızca işlem içi C# sınıf kitaplığı işlevleri için desteklenmektedir. Yalıtılmış çalışan işlemi C# sınıf kitaplığı işlevleri ve diğer tüm dil çalışma zamanları bunun yerine portaldan Azure API Management tümleştirmesini kullanmalıdı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.

İşlevler projesi oluşturma

Visual Studio'daki Azure İşlevleri proje şablonu, Azure'daki bir işlev uygulamasına yayımlayabileceğiniz bir proje oluşturur. Ayrıca, OPENAPI tanım dosyasını (eski adıyla Swagger dosyası) oluşturmayı destekleyen bir HTTP ile tetiklenen işlev 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 aşağıdaki tabloda yer alan değerleri kullanın:

Ayar	Değer	Açıklama
İşlev çalışanı	.NET 6	Bu değer, OpenAPI dosya oluşturma için gereken Azure İşlevleri çalışma zamanının 4.x sürümünde işlem içinde çalışan bir işlev projesi oluşturur.
İşlev şablonu	OpenAPI ile HTTP tetikleyicisi	Bu değer, OpenAPI tanım dosyası oluşturma özelliğine sahip bir HTTP isteği tarafından tetiklenen bir işlev oluşturur.
Çalışma zamanı depolama hesabı için Azurite kullanma (AzureWebJobsStorage)	Seçili	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. Anahtarlar ve yetkilendirme hakkında daha fazla bilgi için bkz. işlev erişim anahtarları.

Proje ayarlarını Azure İşlevleri

İşlev projesini ve OpenAPI desteğiyle HTTP tetikleyici işlevini oluşturmak için Oluştur'u seçin.

Visual Studio, HTTP tetikleyicisi işlev türü için ortak kod içeren adlı Function1 bir proje ve sınıf oluşturur. Ardından, bu işlev şablonu kodunu kendi özelleştirilmiş kodunuzla değiştirirsiniz.

İşlev kodunu güncelleştirme

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

Parametre adı	Açıklama
Saat	Türbin onarımı için en yakın tam saate kadar tahmini süre.
Kapasite	Türbin 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.

Function1.cs proje dosyasında, oluşturulan sınıf kitaplığı kodunun içeriğini aşağıdaki kodla değiştirin:

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

Bu işlev kodu, acil onarımın YesNo uygun maliyetli olup olmadığını belirten veya iletisini döndürür. Ayrıca türbinin temsili 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 JSON isteği gövdesine ve capacity değerlerini hours girin ve Yürüt'e tıklayın.
için 6 ve için hourscapacity2500 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'teAzure'ı ve ardından İleri'yi seçin.
Belirli hedef için Azure İşlev Uygulaması 'nı (Windows) seçerek Windows üzerinde çalışan bir işlev uygulaması oluşturun ve ardından İleri'yi seçin.
İşlev Örneği'nde+ Yeni Azure İşlevi oluştur... seçeneğini belirleyin.

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

Ayar	Değer	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ında yayımladığınızda, yalnızca işlev uygulamanızın yürütmeleri için ödeme alırsınız. Diğer barındırma planları daha yüksek maliyetler doğurmaktadır.
Konum	Hizmetin konumu	Size veya işlevlerinizin eriştirileceği diğer hizmetlere yakın bir bölgedekonum 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 bir 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 oluştur'u da seçin.

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

Ayar	Değer	Açıklama
API adı	TurbineRepair	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 yeni bir API Management örneği oluşturmak için Yeni'yi 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, Yayımla sayfasında Yayımlamaya hazır ifadesinin yer alıp 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 Aç'ı seçin. Oluşturduğunuz işlev uygulaması, varsayılan tarayıcınızdaki Azure portal açılır.
İşlevler bölümünde İşlevler>TürbinIir'i ve ardından İşlev tuşları'nı seçin.
İşlev anahtarları'nın altında varsayılan'ı seçin ve değeri kopyalayın. Artık bu anahtarı işlev uç noktasına erişebilmesi için API Management olarak ayarlayabilirsiniz.

API Management'ı yapılandırma

Yayımla sekmesinde Barındırma'nın yanındaki üç noktayı (...) veardından API'yi Azure portal aç'ı seçin. Oluşturduğunuz API Management örneği, varsayılan tarayıcınızdaki Azure portal açılır. Bu API Management örneği zaten işlev uygulamanıza bağlı.
API'ler'in altında Azure İşlevleri >POST ÇalıştırmasındaOpenAPI Belgesi'ni seçin ve ardından Gelen işleme'nin altında İlke ekle'yi seçin.
Gelen işleme'nin altında, Sorgu parametrelerini ayarla alanına Ad yazıncode, +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.

İşlev anahtarı ayarlandıysa artık API'yi çağırarak 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 OpenAPI tanımını indirebilirsiniz.

1. API'ler'inaltında Azure İşlevleri'da 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'dan 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, listelenen kaynakların silmek istediğiniz 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ştirilen bir işlev oluşturmak için Visual Studio 2022'yi kullandınız. Artık tanımı portaldaki API Management daraltabilirsiniz. ayrıca API Management hakkında daha fazla bilgi edinebilirsiniz.

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