Microsoft Fabric backend'i uygulamak

Bu Microsoft Fabric iş yükü geliştirme örnek deposu , çeşitli hizmetlerle tümleştirme gerektiren uygulamalar oluşturmaya ve lakehouse mimarisiyle tümleştirmeye yönelik bir başlangıç noktasıdır. Bu makale, ortamı ayarlamanıza ve başlamak için gerekli bileşenleri yapılandırmanıza yardımcı olur. Makale, mimarideki temel bileşenleri ve bunların rollerini özetler.

Frontend

Ön uç, kullanıcı deneyimini (UX) ve davranışı yönettiğiniz yerdir. Sorunsuz etkileşimi sağlamak için bir iFrame aracılığıyla Fabric ön uç portalı ile iletişim kurar.

Daha fazla bilgi için Microsoft Fabric İş Yükü Geliştirme Seti ön yüzü bölümüne bakın.

Arka uç

Arka uç hem verileri hem de meta verileri depolar. İş yükü öğeleri ve meta verileri oluşturmak için Oluşturma, Okuma, Güncelleştirme ve Silme (CRUD) işlemlerini kullanır ve depolamadaki verileri doldurmak için işleri yürütür. Ön uç ve arka uç arasındaki iletişim genel API'ler aracılığıyla kurulur.

Azure Relay ve DevGateway

Azure Relay, geliştirici modunda yerel geliştirme ortamı ile Doku arka ucu arasında iletişim sağlar. İş yükü geliştirici modunda geliştiricinin makinesinde çalışır.

DevGateway yardımcı programının iki rolü vardır:

  • Azure Relay kanalındaki iş yükünü yönetir ve belirli bir çalışma alanı bağlamında Fabric ile yerel iş yükü örneğinin kaydını düzenler. Yardımcı program, kanal bağlantısı kesildiğinde kaydı kaldırma işlemini işler.
  • Fabric'den iş yüküne yapılan API çağrılarını yönlendirmek için Azure Relay ile birlikte çalışır.

İş Yükü Kontrol API çağrıları doğrudan iş yükünden Fabric'e yapılır. Çağrılar için Azure Relay kanalı gerekli değildir.

Lakehouse tümleştirmesi

İş yükü geliştirme seti mimarisi, verileri kaydetme, okuma ve getirme gibi işlemler için lakehouse mimarisiyle sorunsuz bir şekilde tümleşir. Güvenli ve kimliği doğrulanmış iletişimin sağlanmasına yardımcı olmak için Azure Relay ve Doku SDK'sı aracılığıyla etkileşim kolaylaştırılır. Daha fazla bilgi için bkz . Müşteri verileriyle çalışma.

Kimlik doğrulaması ve güvenlik

Microsoft Entra ID, mimarideki tüm etkileşimlerin yetkilendirilmiş ve güvenli olduğundan emin olarak güvenli kimlik doğrulaması için kullanılır.

Geliştirme kiti genel bakışı, mimarimize dair bir bakış sunar. Projelerin nasıl yapılandırıldığı, kimlik doğrulama yönergeleri ve kullanmaya başlama hakkında daha fazla bilgi için aşağıdaki makalelere bakın:

Doku SDK'sının Doku ile nasıl tümleştiriliyor olduğunu gösteren diyagram.

Ön uç, iFrame aracılığıyla Fabric ön uç portalıyla iletişim kurar. Portal, açık genel API'lerine çağrılar yaparak Fabric arka planıyla etkileşim kurar.

Arka uç geliştirme ortamı ile Fabric arka ucu arasındaki etkileşimler için Azure Relay bir kanal görevi görür. Ayrıca, arka uç geliştirme kutusu Lakehouse ile sorunsuz bir şekilde tümleşir. İletişim, arka uç geliştirme kutusunda yüklü Olan Azure Relay ve Doku Yazılım Geliştirme Seti (SDK) kullanılarak kolaylaştırılır.

Bu bileşenlerdeki tüm iletişimler için kimlik doğrulaması Microsoft Entra aracılığıyla sağlanır. Microsoft Entra, ön uç, arka uç, Azure Relay, Doku SDK'sı ve Lakehouse arasındaki etkileşimler için güvenli ve kimliği doğrulanmış bir ortam sağlar.

Önkoşullar

  • .NET 7.0 SDK
  • Visual Studio 2022

NuGet Paket Yöneticisi Visual Studio yüklemenizle tümleştirildiğinden emin olun. Bu araç, projemiz için gerekli dış kitaplıkların ve paketlerin kolay yönetimi için gereklidir.

NuGet paket yönetimi

  • <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile> ve <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>: Bu özellikler, Hata Ayıklama ve Sürüm modları için NuGet paketini oluşturmak için kullanılan NuSpec dosyalarının yolunu belirtir. NuSpec dosyası paketle ilgili kimliği, sürümü, bağımlılıkları ve diğer ilgili bilgiler gibi meta verileri içerir.

  • <GeneratePackageOnBuild>true</GeneratePackageOnBuild>: olarak ayarlandığında true, bu özellik derleme işlemine her derleme sırasında otomatik olarak bir NuGet paketi oluşturmasını belirtir. Bu özellik, paketin projedeki en son değişikliklerle her zaman güncel olduğundan emin olmak için kullanışlıdır.

  • <IsPackable>true</IsPackable>: olarak ayarlandığında true, bu özellik projenin bir NuGet paketine paketlenebilir olduğunu gösterir. Paketlenebilir olmak, derleme işlemi sırasında NuGet paketleri üretmeyi amaçlayan projeler için temel bir özelliktir.

Hata ayıklama modu için oluşturulan NuGet paketi, derleme işleminden sonra src\bin\Debug dizininde bulunur.

Bulut modunda çalışırken, Visual Studio derleme yapılandırmasını Release olarak değiştirip paketinizi derleyebilirsiniz. Oluşturulan paket dizininde src\bin\Release bulunur. Daha fazla bilgi için bkz . Bulut modunda çalışma kılavuzu.

Bağımlılıklar

  • Şablon arka plan örneği aşağıdaki Azure SDK paketlerine bağlıdır:

    • Azure.Core
    • Azure.Identity
    • Azure.Storage.Files.DataLake
    • Microsoft Kimlik paketi

NuGet Paket Yöneticisi yapılandırmak için, derleme işlemine başlamadan önce Paket Kaynakları bölümünde yolu belirtin.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
    <BuildDependsOn>PreBuild</BuildDependsOn>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <IsPackable>true</IsPackable>
  </PropertyGroup>
  
  <PropertyGroup Condition="'$(Configuration)' == 'Release'">
    <NuspecFile>Packages\manifest\ManifestPackageRelease.nuspec</NuspecFile>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)' == 'Debug'">
    <NuspecFile>Packages\manifest\ManifestPackageDebug.nuspec</NuspecFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Azure.Core" Version="1.38.0" />
    <PackageReference Include="Azure.Identity" Version="1.11.0" />
    <PackageReference Include="Azure.Storage.Files.DataLake" Version="12.14.0" />
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.9" />
    <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="7.0.5" />
    <PackageReference Include="Microsoft.Extensions.Logging.Debug" Version="7.0.0" />
    <PackageReference Include="Microsoft.Identity.Client" Version="4.60.3" />
    <PackageReference Include="Microsoft.IdentityModel.Protocols" Version="6.30.1" />
    <PackageReference Include="Microsoft.IdentityModel.Protocols.OpenIdConnect" Version="6.30.1" />
    <PackageReference Include="Microsoft.IdentityModel.Tokens" Version="6.30.1" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
  </ItemGroup>

  <ItemGroup>
    <Folder Include="Properties\ServiceDependencies\" />
  </ItemGroup>

  <Target Name="PreBuild" BeforeTargets="PreBuildEvent">
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\RemoveErrorFile.ps1 -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ManifestValidator.ps1 -inputDirectory .\Packages\manifest\ -inputXml WorkloadManifest.xml -inputXsd WorkloadDefinition.xsd -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ItemManifestValidator.ps1 -inputDirectory .\Packages\manifest\ -inputXsd ItemDefinition.xsd -outputDirectory ValidationScripts\" />
    <Exec Command="powershell.exe -ExecutionPolicy Bypass -File ValidationScripts\ValidateNoDefaults.ps1 -outputDirectory ValidationScripts\" />
    <Error Condition="Exists('ValidationScripts\ValidationErrors.txt')" Text="Validation errors with either manifests or default values" File="ValidationScripts\ValidationErrors.txt" />
  </Target>

</Project>

Kullanmaya başlayın

Yerel makinenizde iş yükü örnek projesini ayarlamak için:

  1. Depoyu klonlayın: git clone https://github.com/microsoft/Microsoft-Fabric-workload-development-sample.git çalıştırın.

  2. Visual Studio 2022'de çözümü açın.

  3. Kimlik doğrulama öğreticisindeki yönergeleri izleyerek bir uygulama kaydı ayarlayın. Hem ön uç hem de arka uç projelerinizin makalede açıklanan gerekli kuruluma sahip olduğundan emin olun. Microsoft Entra, mimarideki tüm etkileşimlerin yetkilendirilmiş ve güvenli olduğundan emin olmak için güvenli kimlik doğrulaması için kullanılır.

  4. Microsoft OneLake DFS temel URL'sini güncelleştirin. Fabric ortamınıza bağlı olarak, src\Constants klasöründe değerini güncelleyebilirsiniz. Varsayılan değerdir onelake.dfs.fabric.microsoft.com, ancak URL'yi ortamınızı yansıtacak şekilde güncelleştirebilirsiniz. DFS yolları hakkında daha fazla bilgi için OneLake belgelerine bakın.

  5. İş yükü yapılandırmasını ayarlayın.

    1. workload-dev-mode.json src/Config'den C: öğesine kopyalayın.
    2. workload-dev-mode.json dosyasında aşağıdaki alanları yapılandırmanızla eşleşecek şekilde güncelleştirin:
      • WorkspaceGuid: Çalışma alanı kimliğiniz. Bu değeri, Fabric'de bir çalışma alanı seçtiğinizde tarayıcı URL'sinde bulabilirsiniz. Örneğin, https://app.powerbi.com/groups/<WorkspaceID>/.
      • ManifestPackageFilePath: Bildirim paketinin konumu. Çözümü oluşturduğunuzda, bildirim paketini src\bin\Debug dizinine kaydeder. Bildirim paketi hakkında daha fazla bilgi makalenin ilerleyen bölümlerinde sağlanmıştır.
      • WorkloadEndpointURL: İş yükü uç noktası URL'si.
    3. Paketler/bildirim/WorkloadManifest.xml dosyasında aşağıdaki alanları yapılandırmanızla eşleşecek şekilde güncelleştirin:
      • <AppId>: Microsoft Entra uygulamasının iş yükünün istemci kimliği (Uygulama Kimliği).
      • <RedirectUri>: Yeniden yönlendirme URI'leri. Bu değeri, oluşturduğunuz uygulama kaydında, Kimlik Doğrulaması altında bulabilirsiniz.
      • <ResourceId>: Gelen Microsoft Entra belirteçlerinin hedef kitlesi. Bu bilgileri oluşturduğunuz uygulama kaydında API'yi kullanıma sunma bölümünde bulabilirsiniz.
    4. src/appsettings.json dosyasında aşağıdaki alanları yapılandırmanızla eşleşecek şekilde güncelleştirin:
      • PublisherTenantId: İş yükü yayımcısı kiracısının kimliği.
      • ClientId: Microsoft Entra uygulamasının iş yükünün istemci kimliği (Uygulama Kimliği).
      • ClientSecret: İş yükü Microsoft Entra uygulaması için gizli anahtar.
      • Hedef kitle: Gelen Microsoft Entra belirteçlerinin hedef kitlesi. Bu bilgileri oluşturduğunuz uygulama kaydında API'yi kullanıma sunma bölümünde bulabilirsiniz. Bu ayar, uygulama kimliği URI'si olarak da adlandırılır.

  6. Bir bildirim paketi oluşturun.

    Bildirim paketi dosyası oluşturmak için Fabric_Extension_BE_Boilerplate oluşturun. Derleme, bildirim paketi dosyasını oluşturan üç adımlı bir işlemdir. Şu adımları çalıştırır:

    1. Packages\manifest/ içindeki WorkloadManifest.xml dosyasında ManifestValidator.ps1'i tetikler ve Packages\manifest/ içindeki tüm öğe XML'lerinde (örneğin, Item1.xml) ItemManifestValidator.ps1'i tetikler. Doğrulama başarısız olursa bir hata dosyası oluşturulur. Doğrulama betiklerini ValidationScripts/ içinde görüntüleyebilirsiniz.
    2. Bir hata dosyası varsa, derleme manifestler veya varsayılan değerlerle ilgili Doğrulama hatası ile başarısız olur. Visual Studio'da hata dosyasını görmek için doğrulama sonuçlarında hataya çift tıklayın.
    3. Doğrulama başarılı olduktan sonra WorkloadManifest.xml ve Item1.xml dosyalarını ManifestPackage.1.0.0.nupkg içinde paketle. Sonuçta elde edilen paket src\bin\Debug konumundadır.

    ManifestPackage.1.0.0.nupkg dosyasını workload-dev-mode.json yapılandırma dosyasında tanımlanan yola kopyalayın.

  7. Program.cs, uygulamanızın giriş noktası ve başlangıç betiğidir. Bu dosyada, çeşitli hizmetleri yapılandırabilir, uygulamayı başlatabilir ve web konağını başlatabilirsiniz.

  8. Projenizin derleme ve yürütme için gerekli bağımlılıklara erişebildiğinden emin olmak için oluşturun.

  9. Microsoft'un İndirme Merkezi'nden DevGateway'i indirme

  10. Microsoft.Fabric.Workload.DevGateway.exe uygulamasını çalıştırın ve workload-dev-mode.json alanında belirtilen çalışma alanı için çalışma alanı yöneticisi ayrıcalıklarınaWorkspaceGuidbir kullanıcıyla oturum açın.

    Microsoft oturum açma sayfasının ekran görüntüsü.

    Kimlik doğrulamasından sonra dış iş yükleri, Azure Relay aracılığıyla Doku arka ucuyla iletişim kurar. Bu işlem, belirlenmiş bir ara sunucu düğümü tarafından kolaylaştırılan geçiş kaydını ve iletişim yönetimini içerir. İş yükü bildiriminin yer aldığı paket yüklenir ve yayımlanır.

    Bu aşamada Fabric, iş yükünü algılar ve ayrılmış kapasitesini kullanır.

    Konsolda olası hataları izleyebilirsiniz.

    Hata gösterilmezse bağlantı kurulur, kayıt başarıyla yürütülür ve iş yükü manifestosu sistematik olarak yüklendi.

    Herhangi bir hata olmadan bağlantı yüklemesinin ekran görüntüsü.

  11. Visual Studio'da başlangıç projenizi Boilerplate projesi olarak değiştirin ve Çalıştır'ı seçin.

    Visual Studio'da başlangıç projesi kullanıcı arabiriminin ekran görüntüsü.

Boilerplate örnek projeyle çalışın

Kod oluşturma

REST API'leri kullanarak bir iş yükü oluşturmayı göstermek için Boilerplate C# ASP.NET Core örneğini kullanıyoruz. Örnek, İş Yükü API'sinin Swagger belirtimini temel alan sunucu saplamaları ve sözleşme sınıfları oluşturmayla başlar. Çeşitli Swagger kod oluşturma araçlarından herhangi birini kullanarak kodu oluşturabilirsiniz. Boilerplate örneği NSwag kullanır. Örnek, NSwag kod oluşturucusunu sarmalayan GenerateServerStub.cmd komut satırı betiğini içerir. Betik, NSwag yükleme dizininin tam yolunu içeren tek bir parametre alır. Ayrıca Swagger tanım dosyasını (swagger.json) ve klasördeki yapılandırma dosyasını (nswag.json) denetler.

Bu betiğin yürütülmesi WorkloadAPI_Generated.cs adlı bir C# dosyası oluşturur. Bu dosyanın içeriği, sonraki bölümlerde açıklandığı gibi mantıksal olarak üç bölüme ayrılabilir.

ASP.NET Core stub kontrolcüler

ItemLifecycleController ve JobsController sınıfları, İş Yükü API'sinin iki alt kümesi için ASP.NET Core denetleyicilerinin ince uygulamalarıdır: öğe yaşam döngüsü yönetimi ve işler. Bu sınıflar ASP.NET Core HTTP işlem hattına bağlanır. Bunlar, Swagger belirtiminde tanımlanan API yöntemleri için giriş noktaları görevi görür. Sınıflar, çağrıları iş yükü tarafından sağlanan "gerçek" uygulamaya iletir.

Aşağıda yöntemin bir örneği verilmişti CreateItem :

/// <summary>
/// Called by Microsoft Fabric for creating a new item.
/// </summary>
/// <remarks>
/// Upon item creation Fabric performs some basic validations, creates the item with 'provisioning' state and calls this API to notify the workload. The workload is expected to perform required validations, store the item metadata, allocate required resources, and update the Fabric item metadata cache with item relations and ETag. To learn more see [Microsoft Fabric item update flow](https://updateflow).
/// <br/>
/// <br/>This API should accept [SubjectAndApp authentication](https://subjectandappauthentication).
/// <br/>
/// <br/>##Permissions
/// <br/>Permissions are checked by Microsoft Fabric.
/// </remarks>
/// <param name="workspaceId">The workspace ID.</param>
/// <param name="itemType">The item type.</param>
/// <param name="itemId">The item ID.</param>
/// <param name="createItemRequest">The item creation request.</param>
/// <returns>Successfully created.</returns>
[Microsoft.AspNetCore.Mvc.HttpPost, Microsoft.AspNetCore.Mvc.Route("workspaces/{workspaceId}/items/{itemType}/{itemId}")]
public System.Threading.Tasks.Task CreateItem(System.Guid workspaceId, string itemType, System.Guid itemId, [Microsoft.AspNetCore.Mvc.FromBody] CreateItemRequest createItemRequest)
{

 return _implementation.CreateItemAsync(workspaceId, itemType, itemId, createItemRequest);
}

İş yükü uygulaması için arabirimler

IItemLifecycleController ve IJobsController daha önce bahsedilen "gerçek" uygulamalar için arabirimlerdir. Denetleyiciler tarafından uygulanan aynı yöntemleri tanımlarlar.

Sözleşme sınıflarının tanımı

C# sözleşme sınıfları, API'lerin kullandığı sınıflardır.

Uygulama

Kod oluşturduktan sonraki adım, IItemLifecycleController ve IJobsController arabirimlerini uygulamaktır. Boilerplate örneğinde, ItemLifecycleControllerImpl ve JobsControllerImpl bu arabirimleri uygular.

Örneğin, bu kod CreateItem API'sinin uygulamasıdır:

/// <inheritdoc/>
public async Task CreateItemAsync(Guid workspaceId, string itemType, Guid itemId, CreateItemRequest createItemRequest)
{
 var authorizationContext = await _authenticationService.AuthenticateControlPlaneCall(_httpContextAccessor.HttpContext);
 var item = _itemFactory.CreateItem(itemType, authorizationContext);
 await item.Create(workspaceId, itemId, createItemRequest);
}

Öğe yükünü işleme

Çeşitli API yöntemleri, istek gövdesinin parçası olarak çeşitli türlerde "yük" kabul eder veya yanıtın bir parçası olarak yük döndürür. Örneğin, CreateItemRequest özelliğine creationPayload sahiptir.

"CreateItemRequest": {
 "description": "Create item request content.",
 "type": "object",
 "additionalProperties": false,
 "required": [ "displayName" ],
 "properties": {
 "displayName": {
  "description": "The item display name.",
  "type": "string",
  "readOnly": false
 },
 "description": {
  "description": "The item description.",
  "type": "string",
  "readOnly": false
 },
 "creationPayload": {
  "description": "Creation payload specific to the workload and item type, passed by the item editor or as Fabric Automation API parameter.",
  "$ref": "#/definitions/CreateItemPayload",
  "readOnly": false
 }
 }
}

Bu yük özelliklerinin türleri Swagger belirtiminde tanımlanır. Her tür yük için özel bir tür vardır. Bu türler belirli bir özellik tanımlamaz ve herhangi bir özelliğin dahil edilmesine izin verir.

Aşağıda türün bir örneği verilmişti CreateItemPayload :

"CreateItemPayload": {
 "description": "Creation payload specific to the workload and item type.",
 "type": "object",
 "additionalProperties": true
}

Oluşturulan C# sözleşme sınıfları olarak partialtanımlanır. Özellikleri tanımlanmış bir sözlüğü vardır.

Bir örnek aşağıda verilmiştir:

/// <summary>
/// Creation payload specific to the workload and item type.
/// </summary>
[System.CodeDom.Compiler.GeneratedCode("NJsonSchema", "13.20.0.0 (NJsonSchema v10.9.0.0 (Newtonsoft.Json v13.0.0.0))")]
public partial class CreateItemPayload
{
 private System.Collections.Generic.IDictionary<string, object> _additionalProperties;

 [Newtonsoft.Json.JsonExtensionData]
 public System.Collections.Generic.IDictionary<string, object> AdditionalProperties
 {
  get { return _additionalProperties ?? (_additionalProperties = new System.Collections.Generic.Dictionary<string, object>()); }
  set { _additionalProperties = value; }
 }
}

Kod, özellikleri okumak ve döndürmek için bu sözlüğü kullanabilir. Ancak, daha iyi bir yaklaşım, karşılık gelen türleri ve adları kullanarak belirli özellikleri tanımlamaktır. Özellikleri verimli bir şekilde tanımlamak için oluşturulan sınıflarda bildirimini kullanabilirsiniz partial .

Örneğin, CreateItemPayload.cs dosyası sınıfı için CreateItemPayload tamamlayıcı bir tanım içerir.

Bu örnekte tanım şu özelliği ekler Item1Metadata :

namespace Fabric_Extension_BE_Boilerplate.Contracts.FabricAPI.Workload
{
    /// <summary>
    /// Extend the generated class by adding item-type-specific fields.
    /// In this sample every type will have a dedicated property. Alternatively, polymorphic serialization could be used.
    /// </summary>
    public partial class CreateItemPayload
    {
        [Newtonsoft.Json.JsonProperty("item1Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item1Metadata Item1Metadata { get; init; }
    }
}

Ancak, iş yükü birden çok öğe türünü destekliyorsa, sınıfın CreateItemPayload öğe türü başına bir tanede farklı türlerdeki oluşturma yükünü işleyebilmesi gerekir. İki seçeneğiniz vardır. Ortak Şablon örneğinde kullanılan daha basit yol, her biri farklı bir öğe türü için oluşturma yükünü temsil eden birden çok isteğe bağlı özellik tanımlamaktır. Ardından her istek, oluşturulan öğe türüne göre bu özellik kümelerinden yalnızca birine sahiptir. Alternatif olarak, polimorfik serileştirme uygulayabilirsiniz, ancak bu seçenek önemli bir avantaj sağlamadığından örnekte gösterilmiyor.

Örneğin, iki öğe türünü desteklemek için sınıf tanımının aşağıdaki örnekte olduğu gibi genişletilmesi gerekir:

namespace Fabric_Extension_BE_Boilerplate.Contracts.FabricAPI.Workload
{
    public partial class CreateItemPayload
    {
        [Newtonsoft.Json.JsonProperty("item1Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item1Metadata Item1Metadata { get; init; }

        [Newtonsoft.Json.JsonProperty("item2Metadata", Required = Newtonsoft.Json.Required.Default, NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore)]
        public Item2Metadata Item2Metadata { get; init; }
    } 
}

Not

İş yüküne gönderilen veri paketi istemci tarafından oluşturulur. Öğe düzenleyicisi iFrame veya Doku Otomasyonu REST API'si olabilir. İstemci, doğru yükü göndermek ve öğe türüyle eşleştirmekten sorumludur. İş yükü doğrulamadan sorumludur. Doku bu yükü opak bir nesne olarak ele alır ve yalnızca istemciden iş yüküne aktarır. Benzer şekilde, iş yükü tarafından istemciye döndürülen bir yük için yükün doğru şekilde işlenmesi iş yükünün ve istemcinin sorumluluğundadır.

Örneğin, bu kod, Ortak Örnek öğe1 uygulamasının yükü nasıl işlediğini gösterir:

protected override void SetDefinition(CreateItemPayload payload)
{
 if (payload == null)
 {
  Logger.LogInformation("No payload is provided for {0}, objectId={1}", ItemType, ItemObjectId);
  _metadata = Item1Metadata.Default.Clone();
  return;
 }

 if (payload.Item1Metadata == null)
 {
  throw new InvalidItemPayloadException(ItemType, ItemObjectId);
 }

 if (payload.Item1Metadata.Lakehouse == null)
 {
  throw new InvalidItemPayloadException(ItemType, ItemObjectId)
   .WithDetail(ErrorCodes.ItemPayload.MissingLakehouseReference, "Missing Lakehouse reference");
 }

 _metadata = payload.Item1Metadata.Clone();
}

Sorun giderme ve hata ayıklama

Sonraki bölümlerde dağıtımınızda sorun giderme ve hata ayıklama işlemleri açıklanmaktadır.

Bilinen sorunlar ve çözümler

Bilinen sorunlar ve bunları çözmenin yolları hakkında bilgi edinin.

Eksik istemci gizli anahtarı

Hata:

Microsoft.Identity.Client.MsalServiceException: Yapılandırma sorunu kimlik doğrulamasını engelliyor. Ayrıntılar için sunucudan gelen hata iletisini denetleyin. Yapılandırmayı uygulama kayıt portalında değiştirebilirsiniz. Ayrıntılar için bkz https://aka.ms/msal-net-invalid-client .

Özgün özel durum: AADSTS7000215: Geçersiz bir istemci gizli dizisi sağlandı. İstekte gönderilen gizli verinin, uygulama app_guid ayarına eklenen bir gizli değeri olduğundan ve istemci gizli kimliği olmadığından emin olun.

Çözüm: appsettings.json'de doğru istemci gizli dizisinin tanımlandığından emin olun.

Hata:

Microsoft.Identity.Client.MsalUiRequiredException: AADSTS65001: Kullanıcı veya yönetici uygulamayı kimliğiyle <example ID>kullanmayı onaylamadı. Bu kullanıcı ve kaynak için etkileşimli yetkilendirme isteği gönderin.

Çözüm:

  1. Öğe düzenleyicisinde, sayfanın en altına gidin ve Kimlik Doğrulama Sayfasına Git'i seçin.

  2. Kapsamlar altında .default yazın ve ardından Erişim belirteci al'ı seçin.

  3. İletişim penceresinde revizyonu onaylayın.

Kapasite seçimi nedeniyle öğe oluşturulamıyor

Hata:

PriorityPlacement: Öncelik belirleme için kullanılabilir temel hizmet yoktur. Yalnızca name, guidve workload-name kullanılabilir.

Çözüm:

Kullanıcı olarak yalnızca Deneme kapasitesine erişiminiz olabilir. Erişiminiz olan bir kapasite kullandığınızdan emin olun.

404 (NotFound) hatasıyla dosya oluşturma hatası

Hata:

FilePath için yeni dosya oluşturulamadı: 'workspace-id'/'lakehouse-id'/Files/data.json. Yanıt durum kodu başarılı olduğunu göstermiyor: 404 (NotFound).

Çözüm:

Ortamınıza uygun OneLake DFS URL'si ile çalıştığınızdan emin olun. Örneğin, bir PPE ortamıyla çalışıyorsanız, EnvironmentConstants.OneLakeDFSBaseUrl dosyasındaki uygun URL'ye değiştirin.

Hata Ayıklama (Debug)

Çeşitli işlemlerin sorunlarını giderirken, davranışı analiz etmek ve hatalarını ayıklamak için kodda kesme noktaları ayarlayabilirsiniz. Etkili hata ayıklama için şu adımları izleyin:

  1. Kodu geliştirme ortamınızda açın.
  2. İlgili işlem işleyici işlevine gidin (örneğin, CRUD işlemleri için OnCreateFabricItemAsync veya execute işlemleri için bir denetleyicideki uç nokta).
  3. Kesme noktalarını kodu incelemek istediğiniz belirli satırlara yerleştirin.
  4. Uygulamayı hata ayıklama modunda çalıştırın.
  5. Hata ayıklamak istediğiniz ön uçtan işlemi tetikleme.

Hata ayıklayıcı, değişkenleri inceleyebilmeniz, kodda adım adım ilerleyebilmeniz ve sorunları tanımlayabilmeniz için belirtilen kesme noktalarında yürütmeyi duraklatır.

Hata ayıklama için kesme noktaları içeren örnek programın ekran görüntüsü.

Çalışma alanı

Arka ucu örnek iş yükü projesine bağlıyorsanız, öğenizin bir kapasiteyle ilişkilendirilmiş bir çalışma alanına ait olması gerekir. Varsayılan olarak, Çalışma Alanım çalışma alanı bir kapasiteyle ilişkili değildir. Aksi takdirde, aşağıdaki ekran görüntüsünde gösterilen hatayı alabilirsiniz:

Örnek iş yükü öğesini adlandırmak için kullanıcı arabiriminin ekran görüntüsü.

  1. Adlandırılmış çalışma alanına geçin. Varsayılan çalışma alanı adını Çalışma alanım olarak bırakın.

  2. Doğru çalışma alanından örnek iş yükünü yükleyin ve testlerle devam edin:

Katkıda Bulunun

Bu projeye katkıları memnuniyetle karşılıyoruz. Herhangi bir sorun bulursanız veya yeni özellikler eklemek isterseniz şu adımları izleyin:

  1. Depoyu forklayın.
  2. Özelliğiniz veya hata düzeltmeniz için yeni bir dal oluşturun.
  3. Değişikliklerinizi yapın ve sonra commit edin.
  4. Değişikliklerinizi çatalladığınız deponuza gönderin.
  5. Değişikliklerinizin net bir açıklamasını içeren bir çekme isteği oluşturun.

İlgili içerik

  • Last updated on