NOT: Bu site kullanımdan kaldırılmıştır. Site 31 Ocak 2023'ten sonra kapatılacak ve trafik https://protobuf.dev adresindeki yeni siteye yönlendirilecek. Bu sırada, yalnızca protobuf.dev'de güncellemeler yapılacak.

Google.Protobuf.WellknownTypes.FieldMask

FieldMask, sembolik alan yollarını gösterir. Örneğin:

Özet

path: "f.a" yolları: "f.b.d"

Burada f, bazı kök iletilerdeki bir alanı, f içindeki iletide bulunan a ve b alanlarını; d f.b içindeki iletide bulunan bir alanı temsil eder.

Alan maskeleri, bir alma işlemi tarafından döndürülmesi veya güncelleme işlemiyle değiştirilmesi gereken alanların bir alt kümesini belirtmek için kullanılır. Alan maskelerinde de özel bir JSON kodlaması bulunur (aşağıya bakın).

Projeksiyonlarda Alan Maskeleri

Tahmin bağlamında kullanıldığında bir yanıt mesajı veya alt mesaj, yalnızca maskede belirtilen alanları içerecek şekilde API tarafından filtrelenir. Örneğin, önceki örnekte verilen maske bir yanıt mesajına aşağıdaki gibi uygulanır:

f {
  a : 22
  b {
    d : 1
    x : 2
  }
  y : 13
}
z: 8

Sonuç,x, y ve z alanları için belirli değerler içermez (değerleri varsayılan olarak ayarlanıp proto metin çıkışı atlanır):

f {
  a : 22
  b {
    d : 1
  }
}

Yol dizesinin son konumu hariç, yinelenen alana izin verilmez.

Bir alma işleminde bir FieldMask nesnesi yoksa işlem, tüm alanlara uygulanır (tüm alanların bir FieldMask'i belirtilmiş gibi).

Alan maskesinin üst düzey yanıt mesajı için geçerli olması gerekmediğini unutmayın. REST alma işlemi olduğunda, alan maskesi doğrudan yanıta uygulanır. Ancak REST listesi işlemi olması durumunda maske, döndürülen kaynak listesindeki her mesaja uygulanır. REST özel yöntemi kullanılıyorsa diğer tanımlar kullanılabilir. Maske geçerli olduğunda API'deki beyanıyla birlikte açıkça belgelenecektir. Her durumda, döndürülen kaynak/kaynaklar üzerindeki etki API'ler için gerekli davranıştır.

Güncelleme İşlemlerindeki Alan Maskeleri

Güncelleme işlemlerindeki bir alan maskesi, hedeflenen kaynağın hangi alanlarının güncelleneceğini belirtir. API'nin yalnızca maskede belirtilen alanların değerlerini değiştirip diğerlerini dokunulmadan bırakması gerekir. Güncellenen değerleri açıklamak için bir kaynak aktarılırsa API, maskenin kapsamadığı tüm alanların değerlerini yoksayar.

Güncelleme işlemi için yinelenen bir alan belirtilirse yeni değerler, hedef kaynakta mevcut olan yinelenen değerlerin üzerine yazar. Yinelenen bir alana yalnızca paths dizesinin son konumunda izin verildiğini unutmayın.

Bir güncelleme işlemi için alan maskesinin son konumunda bir alt mesaj belirtilirse hedef kaynaktaki mevcut alt mesajın üzerine yazılır. Hedef mesaja göre:

f {
  b {
    d : 1
    x : 2
  }
  c : 1
}

Ayrıca bir güncelleme mesajı:

f {
  b {
    d : 10
  }
}

Alan maskesi şuysa:

yollar: "f.b"

sonuç şöyle olur:

f {
  b {
    d : 10
  }
  c : 1
}

Ancak güncelleme maskesi şuysa:

yollar: "f.b.d"

sonuç şöyle olur:

f {
  b {
    d : 10
    x : 2
  }
  c : 1
}

Bir alanın değerini varsayılan değere sıfırlayabilmek için alanın maske içinde olması ve sağlanan kaynakta varsayılan değere ayarlanması gerekir. Bu nedenle, bir kaynağın tüm alanlarını sıfırlamak için kaynağın varsayılan bir örneğini sağlayıp maskedeki tüm alanları ayarlayın veya maskeyi aşağıda açıklandığı şekilde vermeyin.

Güncelleme sırasında bir alan maskesi yoksa işlem tüm alanlara uygulanır (örneğin, tüm alanların bir alan maskesi belirtilmiş gibi). Şema gelişimi bu durumda, istemcinin bilmediği ve bu nedenle isteği doldurmadığı alanların varsayılan ayarlarına sıfırlanacağını unutmayın. Bu, istenmeyen bir davranışsa, belirli bir hizmet, istemcinin her zaman bir alan maskesi belirtmesini gerektirebiliyor ve doğru değilse hata oluşturuyor.

Alma işlemlerinde olduğu gibi, istek mesajında güncellenen değerleri açıklayan kaynağın konumu, işlem türüne bağlıdır. Her durumda, API'nin alan maskesinin etkisini dikkate alması gerekir.

HTTP REST için dikkat edilmesi gereken noktalar

Alan maskesi kullanan bir güncelleme işleminin HTTP türü, HTTP semantiğinin karşılanabilmesi için PUT yerine PATCH olarak ayarlanmalıdır (PUT yalnızca tam güncellemeler için kullanılmalıdır).

Alan Maskelerinin JSON Kodlaması

JSON'da bir alan maskesi, yolların virgülle ayrıldığı tek bir dize olarak kodlanır. Her yoldaki alan adı, alt deyimli adlandırma kurallarına dönüştürülür veya bunlardan dönüştürülür.

Örneğin, aşağıdaki mesaj beyanlarını göz önünde bulundurun:

message Profile {
  User user = 1;
  Photo photo = 2;
}
message User {
  string display_name = 1;
  string address = 2;
}

Protoda Profile için bir alan maskesi aşağıdaki gibi görünebilir:

mask {
  paths: "user.display_name"
  paths: "photo"
}

JSON'da aynı maske aşağıdaki şekilde gösterilir:

{
  mask: "user.displayName,photo"
}

Alan Maskeleri ve Oneof Alanları

Alan maskeleri, Alanlar'daki alanları normal alanlar gibi işler. Aşağıdaki mesajı dikkate alın:

message SampleMessage {
  oneof test_oneof {
    string name = 4;
    SubMessage sub_message = 9;
  }
}

Alan maskesi şöyle olabilir:

mask {
  paths: "name"
}

Veya:

mask {
  paths: "sub_message"
}

Tür türlerinden birinin ("bu örnekte test_oneof") yollarında kullanılamayacağını unutmayın.

Devralma

Devralındığı kaynak: Google.Protobuf.ICustomDiagnosticMessage, pb::IMessage< FieldMask >

İnşaat Ustaları ve Yıkıcılar

FieldMask()
FieldMask(FieldMask other)

Özellikler

Descriptor
pbr::MessageDescriptor
Descriptor
pbr::MessageDescriptor pb::IMessage.
Parser
pb::MessageParser< FieldMask >
Paths
pbc::RepeatedField< string >
Alan maskesi yolları grubu.

Herkese açık özellikler

PathsFieldNumber = 1
const int
"yollar" alanı için field numarası.

Herkese açık işlevler

CalculateSize()
int
Protokol Arabellek kablosu biçiminde bu iletinin bayt cinsinden boyutunu hesaplar.
Clone()
Equals(object other)
override bool
Equals(FieldMask other)
bool
GetHashCode()
override int
MergeFrom(FieldMask other)
void
MergeFrom(pb::CodedInputStream input)
void
ToDiagnosticString()
string
Bu FieldMask öğesinin teşhis amacıyla bir dize gösterimini döndürür.
ToString()
override string
WriteTo(pb::CodedOutputStream output)
void

Özellikler

Açıklayıcı

pbr::MessageDescriptor Descriptor

Açıklayıcı

pbr::MessageDescriptor pb::IMessage. Descriptor

Ayrıştırıcı

pb::MessageParser< FieldMask > Parser

Yollar

pbc::RepeatedField< string > Paths

Alan maskesi yolları grubu.

Herkese açık özellikler

YolAlanıNumarası

const int PathsFieldNumber = 1

"yollar" alanı için field numarası.

Herkese açık işlevler

Hesap Boyutu

int CalculateSize()

Protokol Arabellek kablosu biçiminde bu iletinin bayt cinsinden boyutunu hesaplar.

Ayrıntılar
İadeler
Bu iletinin kodlanan bir çıkış akışına yazılması için gereken bayt sayısı.

Klonla

FieldMask Clone()

Şuna eşittir:

override bool Equals(
  object other
)

Şuna eşittir:

bool Equals(
  FieldMask other
)

Arazi Maskesi

 FieldMask()

Arazi Maskesi

 FieldMask(
  FieldMask other
)

GetHashCode'u

override int GetHashCode()

Birleştirme Kaynağı

void MergeFrom(
  FieldMask other
)

Birleştirme Kaynağı

void MergeFrom(
  pb::CodedInputStream input
)

Teşhis Aracı

string ToDiagnosticString()

Bu FieldMask öğesinin teşhis amacıyla bir dize gösterimini döndürür.

Normalde döndürülen değer bir JSON dizesi değeridir (baştaki ve sondaki tırnak işaretleri dahil) ancak değer normalleştirilmemişse veya aralık dışındaysa uyarıyla birlikte bir JSON nesne gösterimi döndürülür. Bu, sorunları teşhis etmeye çalışırken istisnaların atılmaması için kullanılır. Normal JSON biçimlendiricisi, normalleştirilmemiş değerler için bir istisna göndermeye devam eder.

Ayrıntılar
İadeler
Bu değerin bir dize gösterimi.

Dize

override string ToString()

Yazma

void WriteTo(
  pb::CodedOutputStream output
)