İçeriğe geç
AggregaAggrega
Dil seçin: Türkçe
Bu sayfa makine çevirisiyle çevrilmiştir. İngilizce orijinalini okuyun.

Parameters şablon bağlamı

parameters: sütunu, Release tarafından karşılanmış ve sözleşmeye göre doğrulanmış parametre değerlerini taşır. Bu değerlere erişimi iki paralel zihinsel model belirler:

  • Değer şablonu yüzeyleri (Aggregate içindeki component / feature / alt aggregate values: dizeleri, ayrıca Recipe valuesMapping, FeatureRecipe injectMapping ve provides, Workload gövdeleri) parametre değerlerini önceden enterpolasyonu yapılmış sabit değerler olarak tüketir. Çözümleme içindeki enterpolasyon geçişi, Aggregate’in tüm metnini bir şablon olarak değerlendirir ve her {{ .parameters.<slot> }} başvurusunu çözümlenmiş değerle değiştirir; aşağı akıştaki değer şablonu yüzeyleri, şablon bağlamlarında .parameters öğesini hiçbir zaman doğrudan görmez.
  • Yol şablonu yüzeyleri (Release sınırlarında operatörün yazdığı directory: ve subDirectory: şablonları), işleme sırasında yol şablonu değerlendirilirken .parameters.<slot> öğesini doğrudan okur. Birleştirilmiş parametre eşlemi, bir yol şablonunun kapalı izin listesine göre .parameters öğesini okuyabilmesi için işlemenin sonuna kadar okunabilir kalır.

Bu asimetrik yetki — yol şablonları .parameters öğesini doğrudan okur, değer şablonları okumaz — her katmanın ihtiyaç duyduğu şeye sahip olmasını sağlar: geliştirici tarafındaki values: önceden çözümlenmiş ortama özgü verileri değer şablonlarına taşır; operatör tarafındaki yol şablonları ise bölge / ortam / hesap kimliği parametrelerine Aggregate’in values şemasından geçmek zorunda kalmadan başvurur.

Bu sayfa; enterpolasyon geçişini, slot başına değer biçimlerini, Aggregate YAML dizeleri içindeki erişim kalıplarını, yol şablonu istisnasını ve birleştirilmiş eşlemin ne kadar süre okunabilir kaldığını belgeler. Daha geniş Recipe / FeatureRecipe şablon bağlamı biçimi (.values, .infra, .uses vb.) için template-context-contract.md sayfasına bakın. Derleme işlem hattı boyunca şablon konumu başına kullanılabilirlik için expansion-matrix.md sayfasına bakın. Aggregate üzerindeki türlü parametre sözleşmesi bildirim biçimi için entities/aggregate.md §“Typed parameter contracts” bölümüne bakın. Sınır directory: / subDirectory: değerlendirmesinde .parameters.<slot> öğesini içeren yol şablonu değişkeni izin listesi için path-template-variables.md sayfasına bakın.

Parametre yaşam döngüsü

Derleyici parametreleri sıralı dört aşamada çözümler:

  1. Sözleşmenin okunması — Aggregate’in spec.parameters: bloğu, herhangi bir Release değerine bakılmadan önce kendi koşullarına göre denetlenir; böylece hiçbir şeyi kısıtlayamayacak bir slot, onu hiçbir Release sağlamasa bile derlemeyi durdurur. Bir parametrenin kendi bildirimindeki negatif bir minLength veya maxLength, Aggregate yüklenirken parametre ve anahtar adıyla birlikte reddedilir. Slotun kendisindeki ve items, properties veya valuesType altındaki iç içe sözleşmelerdeki her pattern bir düzenli ifade olarak derlenir; derlenemeyen bir ifade parametre, desen ve neden belirtilerek reddedilir. İç içe bir sözleşmedeki uzunluk sınırı bu alt sınıra tabi tutulmaz; bkz. entities/aggregate.md.
  2. Varsayılan doldurma — default: tanımlı olan ve Release tarafından değer sağlanmamış slotlar varsayılan değerlerini alır. .parameters haritası bu noktada kapsamdadır.
  3. Parametre sözleşmesi doğrulaması — birleştirilmiş haritadaki her değer, ister Release tarafından sağlanmış ister bir default: ile doldurulmuş olsun, Aggregate’in spec.parameters.<slot> içinde bildirilen type / enum / min / max / pattern / iç içe yapı kısıtlamalarına göre doğrulanır; bir pattern, sözleşme okunurken derlenen ifadeyle eşleştirilir. .parameters haritası, doğrulayıcının bellek içi bağlamında denetlenen yapılandırılmış yük olarak bulunur.
  4. Enterpolasyon — derleyici, Aggregate’in tüm metnini YAML olarak okumadan önce bir şablon olarak değerlendirir ve her {{ .parameters.<slot> }} başvurusunu çözümlenmiş değerle değiştirir; metindeki diğer her {{ de şablon sözdizimi olarak okunur, bu nedenle kendi çift süslü parantezlerini taşıyan bir değer her {{ ifadesini {{"{{"}} olarak yazar (bkz. Kendi çift süslü parantezlerini taşıyan metin). Enterpolasyon, değer şablonu yüzeyleri için ikame yoludur — bu geçişten sonra değer şablonu bağlamları artık .parameters taşımaz; çevreleyen values: dizelerine yazılmış çözümlenmiş değerleri kullanır. Birleştirilmiş harita, özellikle yol şablonu değerlendirmesini desteklemek için enterpolasyondan sonra da işlemenin tamamı boyunca okunabilir kalır. Okunabilir ömrü derlemenin ömrüyle sınırlıdır: derleyici çözümlenmiş görünümü bir çağırana döndürmek yerine onu kullanan derlemeye verir, bu nedenle o derlemenin dışındaki hiçbir şey haritaya erişemez. Yol şablonu yüzeyi (Release directory: / subDirectory:), .parameters.<slot> değerini işleme sırasında path-template-variables.md sayfasında belgelenen kapalı izin listesine göre okur.

Aggregate YAML dizelerindeki şablonlar (component values:, feature values:, sub-aggregate parameters: aktarım ifadeleri), enterpolasyon geçişi sırasında .parameters haritasını standart Go şablon sözdizimiyle okur. Recipe ve FeatureRecipe dosyalarındaki şablonlar ise şablon bağlamlarında .parameters ALMAZ (yüzey başına sözleşme için aşağıdaki “Aşağı akış şablon bağlamlarıyla sınır” bölümüne bakın).

Kendi çift süslü parantezlerini taşıyan metin

Metnin tamamı bir şablon olduğundan, bir şablona değil bir değere ait olan çift süslü parantezler de şablon eylemi olarak okunur. Bir component’in values: alanında taşınan bir akış platformu tanımı bunun yaygın örneğidir: n8n, bir düğümün parametrelerindeki her ifadeyi ={{ $json.body.message }} örneğindeki gibi çift süslü paranteze alır; bir Flowise istemi bir değişkeni {{question}} olarak adlandırır ve bir Flowise chatflow’u iki düğüm arasındaki her bağlantı için {{chatOpenAI_0.data.instance}} yazar; bir Langflow dışa aktarımı da bileşenlerinin kaynak kodunu taşır ve parantezler orada da görünebilir. Bunlar olduğu gibi bir Aggregate’e yazılırsa, derleme Aggregate’te E0158 ile durur; bu hata Fatal halts sayfasında “A {{ .parameters.* }} reference cannot be interpolated (Bir referans enterpolasyonla yerine konamıyor)” başlığı altında açıklanır. Hatanın gerekçesi, satırı ve şablon motorunun okuyamadığı ilk belirteci adlandırır; bir n8n ifadesi için bu undefined variable "$json" olur. Bir YAML yorumu da şablon metnidir; bu nedenle bir yoruma yazılmış {{ de derlemeyi aynı şekilde durdurur.

Böyle bir değerdeki her {{ ifadesini {{"{{"}} olarak yazın. Bu, sonucu {{ dizesi olan bir şablon eylemidir; dolayısıyla enterpolasyon iki parantezi geri koyar. Kapanış }} için bir şey gerekmez, çünkü bir eylemin dışında düz metindir. Enterpolasyon Aggregate’in metni üzerinde bir kez çalışır ve bir Recipe şablonu .values içinden okuduğunu veri olarak yazar; böylece geri konan parantezler işlenmiş çıktıya dışa aktarıldıkları gibi ulaşır.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

Platform "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}" değerini alır.

Böyle bir tanımı, yukarıdaki gibi, kaçış dizisinin tırnak işaretlerinin sıradan karakterler olduğu bir blok skalerde (|) tutun. Aggregate’in metni enterpolasyondan önce YAML olarak da okunur ve çift tırnaklı bir YAML dizesinin içinde kaçış dizisindeki " dizeyi kapatır; bu durumda dosya artık ayrıştırılamaz ve derleme YAML hatasıyla durur.

.parameters.<slot> erişim kalıbı

Bildirilen her parametre yuvasına .parameters eşlemesindeki bir alan olarak erişilebilir. Türe uygun erişim, bildirilen type ile eşleşir:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

İnterpolasyon geçişi, .parameters eşlemesine karşı bir Go şablonu değerlendirmesi üretir; sonuç, belgedeki şablon ifadesinin yerine geçer. Ardından Component / Feature values: şeması, çözümlemenin interpolasyon sonrası şema doğrulama aşamasında ortaya çıkan değeri doğrular.

Tırnak kullanımı yukarı taşınan türü belirler

Bir dize yaprağını hedefleyen başvuruyu tırnak içine alın; bildirilen diğer her tür için tırnaksız bırakın. Bu kural Aggrega’nın üstüne eklediği bir kural değil, YAML’ın kendi kuralıdır: interpolasyon, karşılanan değeri belgenin baytlarına yerleştirir ve başka hiçbir şey yapmaz; bu nedenle ardından gelen ayrıştırma, sonucu diğer herhangi bir skaleri okuduğu gibi okur. Tırnaksız bir {{ .parameters.cache_ttl_seconds }}, karşılanan değerin kendi türünü taşır; bir tamsayı parametresinin bir tamsayı yaprağına, bir boolean parametresinin de bir boolean yaprağına ulaşmasını sağlayan budur. Tırnak içindeki bir "{{ .parameters.cache_ttl_seconds }}" ise bir dize taşır ve integer ya da boolean olarak bildirilmiş bir yaprak onu reddeder: yazılan değer, Component veya Feature values: şemasında tür nedeniyle başarısız olur ve tanılama, dizenin ayrıca karşılayamayacağı herhangi bir değer uzayı kısıtını değil, tür uyuşmazlığını belirtir.

Skalerini başka metinle paylaşan bir başvuru, nasıl yazılırsa yazılsın bir dizedir, çünkü yerine koyma yapılmış belgede okunacak tek bir skaler vardır: image: app:{{ .parameters.tag }}, app:1.4.0 sonucunu verir. Dize olmayan bir parametrenin bir dize yaprağına yerleşmesi gerektiğinde başvurulacak biçim budur.

Nesne türlü ve dizi türlü slot erişimi

Nesne türlü parametre slotları, bildirilen özelliklerini .parameters.<slot> eşlemesi üzerinde iç içe alanlar olarak sunar. Dizi türlü slotlar Go şablonu dilim semantiğini (range, index, len) sunar.

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

Dizi türlü parametre slotları range ile yinelemeyi destekler:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Release’in sağladığı her öğe, interpolasyondan önce items sözleşmesine göre denetlenir; bu nedenle ana makine adı olmayan bir değer (örneğin *), parametreyi, öğeyi ve biçimi adlandırarak derlemeyi durdurur. format öğesinin kabul ettiği adlar ve her birinin neyi denetlediği vocabulary/compact-form-authoring.md sayfasında listelenir.

Sprig şablon kitaplığı interpolasyon sırasında kullanılabilir ve diziden dizeye kısa dönüşümler için join gibi yardımcılar sağlar:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

Varsayılan doldurma semantiği

default: bildirimi olan bir parametre yuvası, Release yuvayı atladığında varsayılan değerini alır. Varsayılan, sözleşme doğrulama geçişi çalışmadan önce uygulanır; bu nedenle doğrulama, çözümlenmiş (Release tarafından sağlanan ya da varsayılan) değeri görür:

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

required: true olarak işaretlenmiş ve default: içermeyen bir yuva, Release onu atladığında derleme zamanı hatasına (E0165) yol açar. Hata, yazarın düzeltmesi için yuvayı ve sözleşmedeki konumunu belirtir. Ne required: true ne de default: içeren bir yuva isteğe bağlıdır: atlandığında ona yapılan her başvuru boş olarak enterpole edilir ve sonucu ardından Component’in values: şeması değerlendirir.

İç içe nesne parametreleri

Bir parametre, alt öğelerinin kendileri de default: değerleri taşıyan properties: ile birlikte type: object bildirdiğinde, üç yazım durumu farklı sonuçlar üretir. Bu ayrım, parametre bildirimi tek bir skaler yerine yapılandırılmış bir nesne olduğunda (bir veritabanı yapılandırması, bir özellik bayrağı paketi, bir zaman aşımı ve yeniden deneme politikası) önem taşır.

Durum 1 — Release üst yuvayı atlar. Sözleşmenin alt öğe varsayılanları doldurulur. İç içe varsayılanları bildiren Aggregate yazarı amaçladığı davranışı elde eder: operasyon ekibi yuvayı sağlamadığında yapılandırma belgelenmiş varsayılanları kullanır.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

Durum 2 — Release üst öğeyi açıkça boş bir eşlem olarak yazar. Açıkça yazılan boş değer, bilinçli bir devre dışı bırakma olarak dikkate alınır. Alt öğelerin varsayılanları doldurulMAZ; yuva boş kalır. Operasyon ekibi, geçersiz kılma sağlamadan sözleşmenin iç içe varsayılanlarını bastırmak istediğinde bu biçimi kullanın; örneğin aşağı akıştaki bir tüketici yuvanın mevcut ama boş olmasını beklediğinde.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

Durum 1’den bu ayrım bilinçlidir: operasyon ekibi hem “varsayılanları kullan” (yuvayı atlayarak) hem de “varsayılanları bastır” (yuvayı {} olarak yazarak) ifadelerini dile getirebilir. Bu, Aggrega’nın ek açıklamalardaki açık null değerini ele alış biçimini yansıtır: aggrega.ai/<key>: null olarak yazılan bir ek açıklama, ek açıklamayı tamamen atlamaktan farklı, bilinçli bir devre dışı bırakmadır.

Durum 3 — Release üst öğeyi kısmen yazar. Release’in sağladığı alt öğeler yazılan değerlerini alır; Release’in sağlamadığı alt öğeler varsayılanlardan doldurulur.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Bu, seçili alanları geçersiz kılıp geri kalanını sözleşme varsayılanlarında bırakmak isteyen Release yazarları için yaygın durumdur.

Her biçim ne zaman kullanılır

  • Sözleşmenin varsayılanlarının uygulanmasını istediğinizde yuvayı atlayın.
  • Yuvanın bilinçli olarak mevcut ama boş olmasını istediğinizde, yani sözleşmenin varsayılanları ortamınız için yanlış olduğunda ve geçersiz kılmalarınız olmadığında {} yazın.
  • Bazı geçersiz kılmalar istediğinizde ve geri kalanın sözleşmenin varsayılanlarını kullanmasını istediğinizde kısmen yazın.

“Bana varsayılanları ver” beklentisiyle database: {} yazan bir Release yazarı şaşırır: çözümlenmiş değer doldurulmuş varsayılanlar değil, boştur. Varsayılanları almak için yuvayı tamamen atlayın.

Üç durumlu ayrım, her iç içe geçme derinliğinde kardeş öğe başına yapılır. { connection: {}, other_field: "x" } olarak yazılan bir üst öğe, connection öğesinin boş (derinlik 1’de Durum 2) ve other_field öğesinin Release tarafından sağlanan değer (derinlik 0’da Durum 3) olduğu çözümlenmiş bir ağaç üretir: durumlar, alt ağacın tamamı için tek bir karar olarak değil, her kardeş öğe için bağımsız olarak belirlenir.

Aşağı akış şablon bağlamlarıyla sınır

Asimetrik yetki (yol şablonları .parameters değerini doğrudan okur, değer şablonları okumaz) bu sınırdaki temel ayrımdır. Yüzey başına sınır semantiği şöyledir:

  • {{ .parameters.X }} yazan bir Aggregate component-values: şablonu, interpolasyon sırasında doğru biçimde çözümlenir. Çözümlenen değişmez değer, YAML dizesine yerinde yazılır.
  • {{ .parameters.X }} yazan bir Recipe valuesMapping: şablonu bir değer şablonu yüzeyidir; şablon bağlamı .parameters taşımaz. valuesMapping: içinde ortam başına farklılığa ihtiyaç duyan yazarlar bunu çözümlenmiş .values.<key> tüketim yolu üzerinden ifade eder: Aggregate bir parametre sunar, bir Component’in values: alanından ona başvurulur, Release onu karşılar ve interpolasyon sonrası değer Recipe’ye akar.
  • Bir FeatureRecipe injectMapping:, provides: veya pipeline.with: şablonu bir değer şablonu yüzeyidir; Recipe valuesMapping: ile aynıdır. .parameters, şablon bağlamında yer almaz.
  • Bir Workload gövde şablonu (bir Recipe içindeki workload: içeriği) bir değer şablonu yüzeyidir; aynı durum geçerlidir.
  • Bir yol şablonu (Release sınırı directory: / subDirectory:) istisnadır. Yol şablonu bağlamı, kapalı izin listesine göre .parameters.<slot> içerir; başvurular, işleme her sınırın çıktısını yerleştirdiğinde çözümlenir. Yol şablonu değişkenlerinin tam matrisi için path-template-variables.md sayfasına bakın.

Dört alanlı sahiplik sınırı, parametre haritasının belirli bir işlem hattı aşamasında bellekte bulunup bulunmamasıyla değil, parametreleri hangi yüzeyin aldığıyla korunur. Yol şablonları operatör tarafından yazılır ve operatöre aittir; onlara doğrudan parametre erişimi tanımak, operatör kaygılarını (ortam başına yapıt düzeni) operatör yüzeyinin içinde tutar. Değer şablonları katalog tarafından yazılır; onlara doğrudan parametre erişimi tanımamak, katalog tarafındaki yazımı Tek Doğruluk Kaynağı olarak Aggregate sözleşmesine gevşek biçimde bağlı tutar.

Birleştirilmiş parametre haritası, tüm render aşamaları tamamlanana kadar okunabilir kalır, daha fazla değil: yalnızca çözümlendiği derlemeden erişilebilir, dolayısıyla ömrü derlemenin ömrüyle sınırlıdır.

Sütunlar arası köprüleme

Parametreler, çözümleme sırasında çevreleyen values dizelerine yerleştirilir. Yerleştirilen değerler, Aggregate’in kendi kapsamında yazdığı herhangi bir sütuna ulaşabilir: bileşen values: dizeleri, özellik values: dizeleri, alt aggregate parameters: aktarım bildirimleri (burada üst Aggregate’in parametre değeri çözümlenir ve ardından alt Aggregate’in parametre yuvasına aktarılır) ve metadata name: / labels: dizeleri.

Köprüleme tek yönlüdür: bir parametre değeri, Release tarafından sağlanan (veya varsayılan değerle doldurulan) .parameters.<slot> öğesinden başvuru noktasındaki YAML dizesine akar. Parametreler ters yönde akmaz — bir parametre bir values: alanını, bir provides: alanını veya başka herhangi bir sütunun içeriğini okuyamaz. Bu yönlülük, parametre sözleşmesinin yalnızca derleme zamanına ait güvencesinin bir parçasıdır.

Çapraz bağlantılar

  • Aggregate üzerindeki tipli parametre sözleşmesi bildiriminin biçimi için: entities/aggregate.md §“Tipli parametre sözleşmeleri”.
  • Recipes’in temel işleme sırasında tükettiği daha geniş şablon bağlamı için (.values, .infra, .uses, .context.* vb.): template-context-contract.md.
  • Derleme hattı boyunca şablon konumu başına kullanılabilirlik için (hangi alanların hangi değerlendirme konumunda bulunduğu): expansion-matrix.md.
  • Parametre yukarı taşıma kontrol listesi için (sırayla izlenen dört yazım noktası: Aggregate bildirimi, values başvurusu, Release ile karşılama, Recipe tarafından tüketim): vocabulary/data-pillars.md §“Parametre yukarı taşıma kontrol listesi”.
  • Daha geniş veri sütunu kümesi için (values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.