Yansıtma giriş bölgesi gereksinimlerini ve biçimini açma

Bu makalede, Microsoft Fabric'te açık yansıtma için giriş bölgesi ve tablo/sütun işlemi gereksinimleri ayrıntılı olarak açıklanmaktadır.

Açık yansıtılmış veritabanınızı Doku portalı veya Doku çalışma alanınızdaki genel API aracılığıyla oluşturduktan sonra, yansıtılmış veritabanı öğenizin Giriş sayfasında OneLake'te bir giriş bölgesi URL'si alırsınız. Bu giriş bölgesi, uygulamanızın csv de dahil olmak üzere Parquet veya sınırlandırılmış metin biçiminde bir meta veri dosyası oluşturup veri alacağı yerdir. Dosyalar Snappy, GZIP veya ZSTD ile sıkıştırılabilir veya sıkıştırılabilir. Daha fazla bilgi için bkz. desteklenen veri dosyaları ve biçimi.

Giriş bölgesi

Yansıtılan her veritabanı için OneLake'te meta veriler ve delta tabloları için benzersiz bir depolama konumu vardır. Açık yansıtma, uygulamanın bir meta veri dosyası oluşturması ve OneLake'e veri göndermesi için bir giriş bölgesi klasörü sağlar. Yansıtma, bu dosyaları giriş bölgesinde izler ve eklenen yeni tablolar ve veriler için klasörü okur.

Örneğin, giriş bölgesinde oluşturulacak tablolarınız (Table A, Table B, Table C) varsa aşağıdaki URL'ler gibi klasörler oluşturun:

https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableA
https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableB
https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableC

Giriş bölgesindeki meta veri dosyası

Her tablo klasörü bir _metadata.json dosya içermelidir.

Bu tablo meta veri dosyası şu anda yalnızca benzersiz anahtar sütunlarını olarak keyColumnsbelirtmek için bir JSON kaydı içerir.

Örneğin, sütunları C1 ve C2 tablo için bileşik benzersiz anahtar olarak bildirmek için:

{
   "keyColumns" : ["C1", "C2"]
}

keyColumns veya _metadata.json belirtilmezse, güncelleştirme/silme işlemleri mümkün değildir. Bu dosya her zaman eklenebilir, ancak eklendikten keyColumns sonra değiştirilemez.

Giriş bölgesindeki olaylar dosyası

Açık yansıtma çözümü uygulayan bir iş ortağı veya OneLake'e yansıttığınız kaynak türü hakkında bize daha fazla ayrıntı sağlamak isteyen bir müşteriyseniz, yeni _partnerEvents.json bir dosya ekledik. Bu gerekli değildir, ancak kesinlikle önerilir.

Örnek:

{
  "partnerName": "testPartner",
  "sourceInfo": {
    "sourceType": "SQL",
    "sourceVersion": "2019",
    "additionalInformation": {
      "testKey": "testValue"
    }
  }
}

_partnerEvents.json Dosyanın gereksinimleri:

Dosya _partnerEvents.json , tablo başına değil giriş bölgesinde yansıtılmış veritabanı düzeyinde yerleştirilmelidir.
kaynağı sourceType temsil eden herhangi bir açıklayıcı dize olabilir. Bu değer üzerinde kısıtlama yoktur, örneğin: "SQL", "Oracle", "Salesforce", vb.
partnerName seçtiğiniz herhangi bir ada ayarlanabilir ve kuruluşunuzun adını temsil edebilir. Adı tüm yansıtma veritabanlarında tutarlı tutun.

Giriş bölgesindeki veri dosyası ve biçimi

Açık yansıtma, Parquet veya sınırlandırılmış metin biçimlerinde veri alımını destekler. Dosyalar Snappy, GZIP veya ZSTD ile sıkıştırılabilir veya sıkıştırılabilir.

Parquet gereksinimleri

Parquet dosyalarının standart parquet kısıtlamalarına uyması ve parquet mantıksal türleri tarafından tanımlanan geçerli bir mantıksal tür ve fiziksel tür bileşimine sahip olması gerekir.

Örneğin:

TARİh, çağdan bu yana geçen günleri temsil eder ve INT32 olmalıdır.

Geçersiz: logical=DATE, physical=INT64
Geçerli: mantıksal=TARİh, fiziksel=INT32

Sınırlandırılmış metin gereksinimleri

Sınırlandırılmış metin biçimi için, dosyanın ilk satırda üst bilgi satırı olmalıdır.

Sınırlandırılmış metin için dosyanızda _metadata.json ek bilgiler sağlayın. FileExtension özelliği gereklidir. Sınırlandırılmış metin dosyaları aşağıdaki özelliklere ve varsayılanlara sahiptir:

Mülkiyet	Description	Notes
`FirstRowAsHeader`	İlk satır üst bilgisi için True/false.	Sınırlandırılmış metin dosyaları için gereklidir `true` .
`RowSeparator`	Satırları ayırmak için kullanılan karakter.	Varsayılan `\r\n` değeridir. Ayrıca ve 'i `\n`de destekler`\r`.
`ColumnSeparator`	Sütunları ayırmak için kullanılan karakter.	Varsayılan `,` değeridir. Ayrıca , ve `;\|`'yi de destekler`\t`.
`QuoteCharacter`	Sınırlayıcılar içeren değerleri tırnak içine almak için kullanılan karakter.	Varsayılan `"` değeridir. Ayrıca veya boş dize olabilir `'` .
`EscapeCharacter`	Tırnak içinde tırnak işaretleri kaçış için kullanılır.	Varsayılan `\` değeridir. Ayrıca , `/`veya boş da olabilir`"`.
`NullValue`	Null değerlerin dize gösterimi.	, , `"""N/A"`vb. olabilir`"null"`.
`Encoding`	Dosyanın karakter kodlaması.	Varsayılan `UTF-8` değeridir. , , `asciiutf-16`vb. gibi `windows-1252`çok çeşitli kodlamaları destekler.
`SchemaDefinition`	Sütun adlarını, türlerini ve null atanabilirliği tanımlar.	Şema evrimi desteklenmez.
`FileFormat`	Veri dosyasının biçimi.	Belirtilmezse olarak `CSV` varsayılan olarak belirlenir. CSV dışındaki biçimler için olmalıdır `"DelimitedText"` .
`FileExtension`	gibi `.tsv.psv`dosya uzantısını belirtir.	kullanılırken `DelimitedText`gereklidir.

Örneğin, dört sütunlu _metadata.json bir .tsv veri dosyasının dosyası:

{
"KeyColumns": [ "id" ],
"SchemaDefinition": {
    "Columns": [
                  {
                  "Name": "id",
                  "DataType": "Int32"
                  },
                  {
                  "Name": "name",
                  "DataType": "String",
                  "IsNullable": true
                  },
                  {
                  "Name": "age",
                  "DataType": "Int32",
                  "IsNullable": true
                  },
                  {
                  "Name": "seqNum",
                  "DataType": "Int64",
                  "IsNullable": false
                  }
                ]
              },
"FileFormat": "DelimitedText",
"FileExtension": "tsv",
"FileFormatTypeProperties": {
                            "FirstRowAsHeader": true,
                            "RowSeparator": "\r\n",
                            "ColumnSeparator": ",",
                            "QuoteCharacter": "'",
                            "EscapeCharacter": "\",
                            "NullValue": "N/A",
                            "Encoding": "UTF-8"
                         }
}

dosyasında _metadata.jsonyalnızca sınırlandırılmış metin biçimlerinin bir veri türü olması beklenir. Parquet dosyaları, sütun türü bilgilerini belirtmek zorunda değildir. Şu anda desteklenen veri türleri:

Desteklenen veri türü	Description
`Double`	Yüksek duyarlık gerektiğinde kullanılan ondalık sayılar (örneğin, 3,14159).
`Single`	Ondalık değerleri olan ancak Double değerinden daha az kesinlik içeren bir sayı (örneğin, 3,14).
`Int16`	Genellikle -32.768 ile 32.767 arasında küçük bir tamsayı.
`Int64`	Büyük sayılar veya kimlikler için kullanılan çok büyük bir tamsayı.
`Int32`	Sayma veya dizin oluşturma için yaygın olarak kullanılan standart bir tamsayı.
`DateTime`	Tam tarih ve saat değeri (örneğin, 2025-06-17 14:30:00).
`IDate`	Saat içermeyen bir takvim tarihi (örneğin, 2025-06-17).
`ITime`	Tam tarih ve saat değeri (örneğin, 2025-06-17 14:30:00)
`String`	Adlar, etiketler veya açıklamalar gibi metin verileri.
`Boolean`	Genellikle iki durumlu veya evet/hayır seçenekleri için kullanılan true veya false değeri.
`ByteArray`	Dosyalar, görüntüler veya kodlanmış içerik gibi ham ikili veriler.

Biçim gereksinimleri

Giriş bölgesine yazılan tüm dosyalar aşağıdaki biçime sahiptir:

<rowMarker><DataColumns>

rowMarker: sütun adıdır __rowMarker__ (önce ve sonra rowMarkeriki alt çizgi dahil). __rowMarker__ değerler ve davranışlar:

`__rowMarker__` (Senaryo)	Satır hedefte aynı anahtar sütunlarında yoksa	Satır, hedefte aynı anahtar sütunlarla varsa
`0` (Ekle)	Satırı hedefe ekleme	Satırı hedefe ekleyin; yinelenen anahtar sütun denetimi için doğrulama yok.
`1` (Güncelleştir)	Satırı hedefe ekleyin; aynı anahtar sütununa sahip satırın varlığını denetlemek için doğrulama/özel durum yok.	Satırı aynı anahtar sütunuyla güncelleştirin.
`2` (Sil)	Veri değişikliği yok, aynı anahtar sütununa sahip satırın varlığını denetlemek için doğrulama/özel durum yok.	Aynı anahtar sütununa sahip satırı silin.
`4` (Upsert)	Satırı hedefe ekleyin; aynı anahtar sütununa sahip satırın varlığını denetlemek için doğrulama/özel durum yok.	Satırı aynı anahtar sütunuyla güncelleştirin.

Satır sırası: Dosyadaki tüm günlükler işlemde uygulandığı gibi doğal sırada olmalıdır. Bu, aynı satırın birden çok kez güncelleştirilmesini sağlar. Açık yansıtma, dosyalardaki sırayı kullanarak değişiklikleri uygular.
Dosya sırası: Dosyalar monoton olarak artan sayılarla eklenmelidir.
Dosya adı: Dosya adı, ilk dosya için ve 00000000000000000001.parquet ikinci dosya için olduğu gibi 00000000000000000002.parquet 20 basamaktır. Dosya adları sürekli sayılarda olmalıdır. Dosyalar yansıtma hizmeti tarafından otomatik olarak silinir, ancak yayımcı sisteminin sonraki dosyayı sırayla eklemek için başvurabilmesi için son dosya bırakılır.

Önemli

Sütunun __rowMarker__ listedeki son sütun olması gerekir

Sıralı olmayan dosyalar

Sıralı olmayan dosyalar da desteklenir; dosyalar, zaman damgalarına göre okunur. Bunu ve varsayılan olarak eklemeler yerine upsert değişikliklerini belirtmek için _metadata.json dosyasını şu şekilde güncelleştirin:

{
   "keyColumns" : ["id"],
   "fileDetectionStrategy": LastUpdateTimeFileDetection,
   "isUpsertDefaultRowMarker": true
}

'upsert varsayılanı' sıralı olmayan dosyalara bağlı değildir. Aşağıdaki birleşimlerin tümü desteklenir:

fileDetectionStrategy ayarını LastUpdateTimeFileDetection ve isUpsertDefaultRowMarker ayarını true olarak belirleyin.
Yalnızca isUpsertDefaultRowMarker true değerine sahiptir.
Yalnızca FileDetectionStrategy değerini LastUpdateTimeFileDetection olarak belirleyin.
Varsayılan

İlk yükleme

Verilerin açık yansıtılmış veritabanına ilk yüklenmesi için, __rowMarker__ ilk veri dosyasında isteğe bağlıdır ve önerilmez. Yansıtma, mevcut olmadığında __rowMarker__ dosyanın tamamını INSERT olarak ele alır.

Daha iyi performans ve doğru ölçümler için, __rowMarker__ yalnızca güncelleştirme/silme/upsert işleminin uygulanması için artımlı değişiklikler için zorunlu bir alandır.

Artımlı değişiklikler

Açık yansıtma, artımlı değişiklikleri sırayla okur ve bunları hedef Delta tablosuna uygular. Sıra, değişiklik günlüğünde ve dosyaların sırasına göre örtülüdür.

Sütun herhangi bir satırdan/dosyadan bulunduktan sonra __rowMarker__ veri değişiklikleri artımlı değişiklikler olarak kabul edilir.

Güncelleştirilmiş satırlar, tüm sütunlarla birlikte tam satır verilerini içermelidir.

E0001 değerinin Redmond'dan Bellevue'ya değişim işlemi için EmployeeLocationEmployeeID satır geçmişinin bazı örnek parquet verileri. Bu senaryoda, sütun giriş EmployeeIDbölgesindeki meta veri dosyasında anahtar sütunu olarak işaretlendi.

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Redmond,0
E0002,Redmond,0
E0003,Redmond,0
E0001,Bellevue,1

Anahtar sütunları güncelleştirildiyse, önceki anahtar sütunlarında DELETE ve yeni anahtar ve veri içeren bir INSERT satırı tarafından gösterilmelidir. Örneğin, E0001 için benzersiz tanımlayıcıyı __rowMarker__ E0002 olarak değiştirmek için EmployeeID satır geçmişi. DELETE satırı için tüm sütun verilerini sağlamanız gerekmez, yalnızca anahtar sütunları sağlamanız gerekir.

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Bellevue,0
E0001,NULL,2
E0002,Bellevue,0

Tablo işlemleri

Açık yansıtma, tablo ekleme, bırakma ve yeniden adlandırma gibi tablo işlemlerini destekler.

Tablo ekle

Açık yansıtma, uygulama tarafından giriş bölgesine eklenen tüm tabloları alır. Her yinelemede yeni tablolar için yansıtma taramalarını açın.

Tabloyu sil

Açık yansıtma, klasör adını izler. Tablo klasörü silinirse, açık yansıtma tabloyu yansıtılmış veritabanına bırakır.

Bir klasör yeniden oluşturulursa, açık yansıtma tabloyu bırakır ve klasördeki yeni verilerle yeniden oluşturur ve klasörün ETag'i izlenerek gerçekleştirilir.

Tabloyu bırakmaya çalışırken klasörü silmeyi deneyebilirsiniz, ancak açık yansıtmanın hala klasördeki verileri kullanma olasılığı vardır ve bu da yayımcı için silme hatasına neden olur.

Tabloyu yeniden adlandır

Tabloyu yeniden adlandırmak için ilk ve artımlı verilerle klasörü bırakın ve yeniden oluşturun. Verilerin yeniden adlandırılan tabloya yeniden doldurulmalıdır.

Schema

Tablo yolu bir şema klasörü içinde belirtilebilir. Şema giriş bölgesinin bir <schemaname>.schema klasör adı olmalıdır. Birden çok şema olabilir ve bir şemada birden çok tablo olabilir.

Örneğin, giriş bölgesinde oluşturulacak şemalarınız (Schema1, Schema2) ve tablolarınız (Table A, Table B, Table C) varsa, OneLake'de aşağıdaki yollar gibi klasörler oluşturun:

https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableA
https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableB
https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema2.schema/TableC

Tablo sütunları ve sütun işlemleri

Sütun türleri

Giriş bölgesinde basit parke türleri desteklenir.
Karmaşık türler bir JSON dizesi olarak yazılmalıdır.
Coğrafya, görüntüler vb. gibi ikili karmaşık türler giriş bölgesinde ikili tür olarak depolanabilir.

Sütun ekle

Parquet veya CSV dosyalarına yeni sütunlar eklenirse, açık yansıtma sütunları delta tablolarına ekler.

Sütunu silme

Yeni günlük dosyalarından bir sütun bırakılırsa, bu sütunlar için yeni satırlardaki açık yansıtma depoları NULL açılır ve eski satırlarda verilerde sütunlar bulunur. Sütunu silmek için tabloyu bırakın ve tablo klasörünü yeniden giriş bölgesinde oluşturun; bu da Delta tablosunun yeni şema ve verilerle yeniden oluşturulmasına neden olur.

Açık yansıtma her zaman eklenen verilerin önceki sürümündeki tüm sütunları birleştirir. Sütunu kaldırmak için tabloyu/klasörü yeniden oluşturun.

Sütun türünü değiştirme

Sütun türünü değiştirmek için ilk ve artımlı verileri içeren klasörü yeni sütun türüyle bırakın ve yeniden oluşturun. Tabloyu yeniden oluşturmadan yeni bir sütun türü sağlanması hataya neden olur ve bu tablo için çoğaltma durdurulur. Tablo klasörü yeniden oluşturulduğunda, çoğaltma yeni veri ve şemayla devam eder.

Sütunu yeniden adlandır

Sütunu yeniden adlandırmak için tablo klasörünü silin ve klasörü tüm verilerle ve yeni sütun adıyla yeniden oluşturun.

Temizleme işlemi

Yansıtmayı açmaya yönelik temizleme işlemi, işlenen tüm dosyaları veya _ProcessedFilesadlı _FilesReadyToDelete ayrı bir klasöre taşır. Yedi gün sonra dosyalar bu klasörden kaldırılır.

Sonraki adım

Öğretici: Microsoft Fabric açık yansıtılmış veritabanlarını yapılandırma

Monitor Fabric yansıtılmış veritabanı replikasyonunu izleme

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-09-09