Data API oluşturucusunu Azure App Service'e dağıtımını yapmak

Bu kılavuzda, kapsayıcı görüntülerini oluşturmadan veya yönetmeden Azure App Service için Veri API'si Oluşturucusu'nu (DAB) nasıl dağıtabileceğiniz gösterilir. App Service TLS, özel etki alanları, ölçeklendirme, izleme ve Microsoft Entra kimlik doğrulaması için yerleşik destek sağlar.

Azure App Service dağıtımı tamamlandıktan sonra genel mimariyi gösteren diyagram.

Tip

Ortamınızda kapsayıcılar kullanılıyorsa bkz. Deploy to Azure Container Apps veya Deploy to Azure Kubernetes Service.

Prerequisites

Important

Yerleşik .NET App Service yığını .NET çalışma zamanını içerir, ancak .NET SDK'sını içermez. DAB'yi geri yükleyin ve dağıtım paketini yerel geliştirme veya derleme makinenizde derleyin. App Service başladığında dotnet tool restore öğesini çalıştırmayın.

Yapılandırma dosyasını oluşturma

Mevcut veritabanınıza bağlanmak için bir DAB yapılandırma dosyası oluşturun.

  1. Yapılandırma dosyasını ve dağıtım yapıtlarını depolamak için yerel makinenizde boş bir dizin oluşturun.

  2. kullanarak dab inityeni bir temel yapılandırma dosyası başlatın. @env() işlevini, kimlik bilgilerinin yapılandırma dosyasında depolanmasını önlemek için DATABASE_CONNECTION_STRING ortam değişkenine başvurmak amacıyla kullanın.

    dab init --database-type "<database-type>" --connection-string "@env('DATABASE_CONNECTION_STRING')"

    Important

    öğesini, , , veya gibi desteklenen bir veritabanı türüyle değiştirin. Bazı veritabanı türleri başlatma için ek yapılandırma ayarları gerektirir.

  3. Yapılandırmaya en az bir veritabanı varlığı ekleyin. dab add Bir varlığı yapılandırmak için komutunu kullanın. Gerektiği kadar çok varlıklarınız için dab add parçasını tekrarlayın.

    dab add "<entity-name>" --source "<schema>.<table>" --permissions "anonymous:*"

  4. dab-config.json dosyasının içeriğini açın ve gözden geçirin. Aşağıdakileri doğrulayın:

    • data-source.connection-string kullanır @env('DATABASE_CONNECTION_STRING')
    • Varlıklarınız ve izinleriniz doğru

    Important

    Sabit bağlantı dizelerini veya gizli anahtarları dab-config.json içerisine gömmeyin. @env() işlevini kullanarak değerlerin çalışma zamanında ortam değişkenlerinden çözümlenmesini sağlayın.

Derleme için DAB'yi sabitleme

Geliştirme veya derleme makinenizde DAB sürümünü sabitlemek için yerel bir .NET araç bildirimi kullanın. Bildirim, derlemelerin yeniden üretilebilir olmasını sağlar, ancak geri yüklenen DAB ikili dosyalarını içermez. Bu ikili dosyaları bu kılavuzun ilerleyen bölümlerinde dağıtım paketine kopyalayacaksınız.

  1. Proje dizininizde bir .NET yerel araç bildirimi oluşturun.

    dotnet new tool-manifest

  2. Belirli bir Data API builder sürümünü yerel bir araç olarak yükleyin. <dab-version> öğesini, dağıtmak istediğiniz sürümle değiştirin; örneğin 2.0.9.

    dotnet tool install microsoft.dataapibuilder --version "<dab-version>"

  3. Manifesto'nun .config/dotnet-tools.json konumunda mevcut olduğunu doğrulayın.

  4. Geliştirme veya derleme makinesinde sabitlenmiş aracı geri yükleyin.

    dotnet tool restore

    Note

    Geri yükleme işlemi yerel NuGet paket önbelleğini doldurur. App Service dağıtım paketi geri yüklenen çalışma zamanı yükünü içermelidir; yalnızca .config/dotnet-tools.json dağıtmak yeterli değildir.

Yerel olarak test et

Azure dağıtmadan önce çalışma zamanının başladığını ve uç noktalarınızın çalıştığını onaylayın.

  1. bağlantı dizesi yerel ortam değişkeni olarak ayarlayın.

    $env:DATABASE_CONNECTION_STRING = "<your-connection-string>"

  2. DAB çalışma zamanını yerel olarak başlatın.

    dotnet tool run dab start

  3. Swagger kullanıcı arabirimine giderek veya /api/<entity-name>'a istekte bulunarak REST uç noktasını test edin.

  4. GraphQL uç noktasını /graphql adresinde test edin.

  5. Tüm uç noktaları doğruladıktan sonra çalışma zamanını durdurun.

App Service kaynaklarını oluşturma

App Service'te DAB barındırmak için gereken Azure kaynaklarını oluşturun.

  1. Yeni bir kaynak grubu oluşturun. Bu kılavuzdaki tüm yeni kaynaklar için bu kaynak grubunu kullanırsınız.

    az group create --name "<resource-group-name>" --location "<location>"

    Tip

    msdocs-dab-appservice kaynak grubunu adlandırmayı göz önünde bulundurun.

  2. App Service planı oluşturun.

    az appservice plan create --name "<plan-name>" --resource-group "<resource-group-name>" --sku B1 --is-linux

    Note

    Bu kılavuz, Linux'ta B1 (Temel) katmanını kullanır.

  3. .NET 8 çalışma zamanı ve sistem tarafından atanan yönetilen kimlik ile web uygulamasını oluşturun.

    az webapp create --name "<app-name>" --resource-group "<resource-group-name>" --plan "<plan-name>" --runtime "DOTNETCORE:8.0" --assign-identity "[system]"

    Tip

    ile az webapp list-runtimes --os linuxplanınız için kullanılabilir çalışma zamanlarını doğrulayın.

App Service ayarlarını yapılandırma

App Service'in DAB çalıştırmak için ihtiyaç duyduğu ortam değişkenlerini ve başlangıç komutunu yapılandırın.

  1. Veritabanı bağlantı dizesini bir App Service uygulama ayarı olarak ayarlayın.

    az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings DATABASE_CONNECTION_STRING="<your-connection-string>"

    Tip

    Sırlar içermeyen bir bağlantı dizesi kullanın. Bunun yerine, veritabanınızla App Service arasındaki erişimi yönetmek için yönetilen kimlikleri ve Microsoft Entra kimlik doğrulamasını kullanın. Daha fazla bilgi için bkz. Yönetilen kimlikleri kullanan Azure hizmetleri.

  2. DAB'ın dinlediği adresi yapılandırın. Bağlantı noktası 8080 , yerleşik Linux App Service yığını için uygulama bağlantı noktasıdır.

    az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings ASPNETCORE_URLS="http://0.0.0.0:8080"

  3. İlk dağıtımdan önce Always On ve dosya sistemi günlüğünü etkinleştirin. Always On, bu kılavuzda kullanılan B1 katmanında kullanılabilir.

    az webapp config set --name "<app-name>" --resource-group "<resource-group-name>" --always-on true

az webapp log config --name "<app-name>" --resource-group "<resource-group-name>" --application-logging filesystem --docker-container-logging filesystem --level information

  4. Dağıtım paketine dahil edilen DAB çalışma zamanı bileşenini başlatan bir başlatma betiği oluşturun. Proje dizininizde adlı startup.sh bir dosya oluşturun.

    #!/bin/sh
set -eu
exec dotnet ./dab/Microsoft.DataApiBuilder.dll start --config ./dab-config.json

    Important

    startup.sh'nin CRLF yerine LF (Unix) satır sonları kullandığından emin olun. Windows düzenleyicileri varsayılan olarak CRLF ile kaydedebilir ve bu da betiğin Linux App Service ana bilgisayarında başarısız olmasına neden olur.

  5. App Service'te başlangıç komutunu ayarlayın.

    az webapp config set --name "<app-name>" --resource-group "<resource-group-name>" --startup-file "sh startup.sh"

Azure SQL için yönetilen kimliği yapılandırma

Veri kaynağınız Azure SQL ise web uygulamasının sistem tarafından atanan yönetilen kimliğini veritabanında yetkilendirin. Farklı bir veritabanı veya kimlik doğrulama yöntemi kullanıyorsanız bu bölümü atlayın.

  1. Hedef veritabanına Microsoft Entra yöneticisi olarak bağlanın.

  2. Web uygulaması kimliği için bir bağımsız veritabanı kullanıcısı oluşturun ve yalnızca DAB varlıklarınız için gereken izinleri verin. Aşağıdaki örnek okuma ve yazma işlemlerini destekler.

    CREATE USER [<app-name>] FROM EXTERNAL PROVIDER;
ALTER ROLE [db_datareader] ADD MEMBER [<app-name>];
ALTER ROLE [db_datawriter] ADD MEMBER [<app-name>];

    Note

    Microsoft Entra kimlik yayma işlemi web uygulaması oluşturulduktan sonra birkaç dakika sürebilir. CREATE USER kimliği hemen çözümleyemezse, bekleyin ve yeniden deneyin.

  3. DATABASE_CONNECTION_STRING öğesini Azure SQL yönetilen kimlik bağlantı dizesi olarak ayarlayın.

    az webapp config appsettings set --name "<app-name>" --resource-group "<resource-group-name>" --settings DATABASE_CONNECTION_STRING="Server=tcp:<sql-server-name>.database.windows.net,1433;Initial Catalog=<database-name>;Authentication=Active Directory Managed Identity;Encrypt=True;TrustServerCertificate=False;"

App Service’e dağıtım yapın

Geri yüklenen DAB çalışma zamanını uygulama dizininize kopyalayın, ardından ZIP dağıtımı kullanarak dizini dağıtın.

  1. DAB yapılandırmasını, başlangıç betiğini ve geri yüklenen çalışma zamanı yükünü içeren bir uygulama dizini oluşturun.

    Örneklerde DAB sürümü 2.0.9kullanılır. Sürümü, .config/dotnet-tools.json içinde sabitlediğiniz sürümle aynı sürüm olarak ayarlayın.

    $dabVersion = "2.0.9"
$globalPackages = (dotnet nuget locals global-packages --list) -replace '^global-packages:\s*', ''
$dabPayload = Join-Path $globalPackages "microsoft.dataapibuilder/$dabVersion/tools/net8.0/any"
$appDirectory = Join-Path (Get-Location) "app"

Remove-Item $appDirectory -Recurse -Force -ErrorAction SilentlyContinue
New-Item -ItemType Directory -Path (Join-Path $appDirectory "dab") -Force | Out-Null
Copy-Item dab-config.json, startup.sh -Destination $appDirectory
Copy-Item (Join-Path $dabPayload "*") -Destination (Join-Path $appDirectory "dab") -Recurse

if (-not (Test-Path (Join-Path $appDirectory "dab/Microsoft.DataApiBuilder.dll"))) {
    throw "The restored DAB runtime payload wasn't found."
}

    Important

    Sabitlenmiş DAB aracını geri yüklediğiniz aynı makinede bu komutları çalıştırın. Ortamınız NuGet genel paket dizinini geçersiz kılarsa, dotnet nuget locals bu dizinin konumunu belirler.

  2. Taşınabilir / giriş ayırıcıları olan bir ZIP oluşturun. Arşiv kökü, dab-config.json, startup.sh ve dab/ dizinini doğrudan içermelidir. app üst dizinini sıkıştırmayın.

    Remove-Item deploy.zip -Force -ErrorAction SilentlyContinue
tar.exe -a -c -f deploy.zip -C $appDirectory dab-config.json startup.sh dab

    Warning

    Windows'ta, Compress-Archive iç içe girdileri \ ayırıcılarıyla depolayabilir. Kudu ZIP dağıtımı bu arşivi HTTP 400 ile reddedebilir. Ayırıcıları / depolayan bir ZIP aracı kullanın ve dağıtım ayrıntıları olmadan HTTP 400 döndürüyorsa arşiv girdilerini inceleyin.

  3. ZIP paketini App Service'e dağıtın.

    az webapp deploy --resource-group "<resource-group-name>" --name "<app-name>" --src-path deploy.zip --type zip --clean true --restart false --timeout 600000

  4. Dağıtım tamamlandıktan sonra web uygulamasını yeniden başlatın.

    az webapp restart --resource-group "<resource-group-name>" --name "<app-name>"

Dağıtımı doğrulayın.

Dağıtımdan sonra DAB'nin App Service'te başarıyla başlatıldığını onaylayın.

  1. App Service URL'sini açın. Kök yanıt, DAB durumunu ve sürümünü içerir.

    https://<app-name>.azurewebsites.net

  2. Yerel olarak test ettiğiniz varlık yollarını kullanarak REST ve GraphQL uç noktalarını test edin. Dağıtılan uygulama aynı dab-config.jsonkullanır, bu nedenle uç nokta davranışı yerel çalışma zamanınızla eşleşmelidir.

    https://<app-name>.azurewebsites.net/api/<entity-name>
https://<app-name>.azurewebsites.net/graphql

    Note

    Üretim modunda, /health arayanın kapsamlı sistem durumu raporunu görüntüleme yetkisi olmadığında HTTP 403 döndürebilir. Kök ve yetkili varlık uç noktaları başarıyla yanıt verirse, /health öğesinden gelen 403 yanıtı bir başlatma başarısızlığına işaret etmez.

  3. Uç nokta beklenmeyen bir hata döndürürse uygulama günlüklerini gözden geçirin veya indirin. Bu kılavuzda, dağıtımdan önce günlüğe kaydetme etkinleştirildi.

    az webapp log tail --name "<app-name>" --resource-group "<resource-group-name>"

az webapp log download --name "<app-name>" --resource-group "<resource-group-name>" --log-file appservice-logs.zip

Kimlik doğrulamayı yapılandırma (isteğe bağlı)

Üretim kullanımı için Microsoft Entra ID ile App Service uç noktanızı koruyun.

Ayrıntılı adımlar için bkz. App Service kimlik doğrulamasını yapılandırma.

App Service kimlik doğrulamasını etkinleştirdikten sonra, DAB'yi App Service tarafından eklenen kimlik üst bilgilerine güvenecek şekilde yapılandırın. Geliştirme makinenizde bu komutu çalıştırın, ardından ZIP paketini yeniden derleyin ve yeniden dağıtın.

dab configure --runtime.host.authentication.provider AppService

Important

içindeki AppService kimlik doğrulama sağlayıcısı dab-config.json , App Service kimlik doğrulaması tarafından eklenen üst bilgilere güvenir. Bu sağlayıcı üretimde kullanılırken App Service kimlik doğrulamasının etkinleştirildiğinden emin olun. Daha fazla bilgi için bkz. Kolay Kimlik Doğrulaması (App Service).

Note

App Service kimlik doğrulaması uç noktanıza girişi korur. DAB varlık izinleri, çalışma zamanının hangi işlemlere izin verdiğine karar verir. Anonim bir demo için App Service kimlik üst bilgilerine güvenmeyin. Rol tabanlı erişim için App Service kimlik doğrulamasını etkinleştirin ve varlık izinlerinizi, anonymous:* yerine kimliği doğrulanmış veya özel rolleri kullanacak şekilde güncelleştirin.

Dağıtım sorunlarını giderme

Yaygın dağıtım sorunlarını belirlemek için aşağıdaki belirtileri kullanın.

Belirti Neden ve çözüm
ZIP dağıtımı, ayrıntılar olmadan HTTP 400 döndürür ZIP kökünü ve giriş ayırıcılarını inceleyin. ZIP'i / ayırıcılarıyla yeniden oluşturun ve doğrudan dab-config.json, startup.sh ve dab/ içerdiğinden emin olun.
Uygulama HTTP 503 döndürüyor ve günlüklerde No .NET SDKs were found veya The application 'tool' does not exist bulunuyor Başlangıç komutu dotnet tool öğesini çalıştırmaya çalışıyor. Geri yüklenen DAB yüküyle paketi yeniden derleyin ve doğrudan çağırın Microsoft.DataApiBuilder.dll .
Başlatma kullanıcı komutuna ulaşır ancak App Service ısınma işlemi başarısız olur Başlangıç betiğinin LF satır sonlarını kullandığını doğrulayın, sh startup.sh kullanın, DAB payload yollarını onaylayın ve günlüklerde dinleme URL’sini ve veritabanı hatalarını kontrol edin.
DAB başlatılır ancak veritabanı istekleri başarısız olur Web uygulaması yönetilen kimliğinin veritabanı kullanıcısı olarak var olduğunu ve yapılandırılan varlıklar için gerekli izinlere sahip olduğunu doğrulayın.
/health REST veya GraphQL çalışırken HTTP 403 döndürür DAB çalışıyor, ancak arayanın kapsamlı sistem durumu raporunu görüntüleme yetkisi yok. Bunun yerine kök veya yetkili varlık uç noktasını doğrulayın.
Daha büyük bir ZIP dağıtımı HTTP 502 döndürür Yeniden denemeden önce dağıtım geçmişini denetleyin. Belirtilmiş bir zaman aşımıyla eşzamanlı olarak dağıtın, örtük yeniden başlatmayı devre dışı bırakın ve dağıtım tamamlandıktan sonra yeniden başlatın.

Kaynakları temizle

Web uygulamasına ve kaynaklarına artık ihtiyacınız kalmadığında kaynak grubunu silin.

az group delete --name "<resource-group-name>" --yes --no-wait

İlgili içerik

  • Last updated on