Veri API'si oluşturucu yapılandırma şeması başvurusu

Makale
07/10/2024

Veri API'sinin oluşturucusunun altyapısı bir yapılandırma dosyası gerektirir. Data API Builder yapılandırma dosyası, API'nizi ayarlamaya yönelik yapılandırılmış ve kapsamlı bir yaklaşım sağlar ve ortam değişkenlerinden varlığa özgü yapılandırmalara kadar her şeyi ayrıntılı olarak açıklar. JSON biçimli bu belge bir $schema özelliğiyle başlar. Bu kurulum belgeyi doğrular.

özellikler database-type ve connection-string, Azure SQL Veritabanı'ndan Cosmos DB NoSQL API'sine kadar veritabanı sistemleriyle sorunsuz tümleştirme sağlar.

Yapılandırma dosyası şunlar gibi seçenekler içerebilir:

Veritabanı hizmeti ve bağlantı bilgileri
Genel ve çalışma zamanı yapılandırma seçenekleri
Kullanıma sunulan varlık kümesi
Kimlik doğrulama yöntemi
Kimliklere erişmek için gereken güvenlik kuralları
API ile veritabanı arasında ad eşleme kuralları
Çıkarılabilen varlıklar arasındaki ilişkiler
Belirli veritabanı hizmetleri için benzersiz özellikler

Söz dizimine genel bakış

Burada, yapılandırma dosyasındaki birincil "bölümlerin" hızlı dökümü verilmiştir.

{
  "$schema": "...",
  "data-source": { ... },
  "data-source-files": [ ... ],
  "runtime": {
    "rest": { ... },
    "graphql": { .. },
    "host": { ... },
    "cache": { ... },
    "telemetry": { ... },
    "pagination": { ... }
  }
  "entities": [ ... ]
}

Üst düzey özellikler

Tablo biçimindeki en üst düzey özelliklerin açıklaması aşağıdadır:

Mülk	Tarif
$schema	Doğrulama için JSON şemasını belirtir ve yapılandırmanın gerekli biçime uygun olmasını sağlar.
veri kaynağı	veritabanı türü ve veritabanı bağlantısını kurmak için gereken bağlantı dizesihakkındaki ayrıntıları içerir.
veri kaynağı dosyalarını	Diğer veri kaynaklarını tanımlayabilen diğer yapılandırma dosyalarını belirten isteğe bağlı bir dizi.
çalışma zamanı	REST, GraphQL, konak, önbellekve telemetriiçin alt özellikler dahil olmak üzere çalışma zamanı davranışlarını ve ayarlarını yapılandırır.
varlıkları	api aracılığıyla kullanıma sunulan varlık kümesini (veritabanı tabloları, görünümler vb.) tanımlar; bunların eşlemeleri, izinlerive ilişkileri.

Örnek yapılandırma

Burada yalnızca tek bir basit varlık için gerekli özellikleri içeren örnek bir yapılandırma dosyası verilmiştır. Bu örnek, en düşük senaryoya yöneliktir.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('sql-connection-string')"
  },
  "entities": {
    "Book": {
      "source": "dbo.books",
      "permissions": [{
          "actions": ["*"],
          "role": "anonymous"
      }]
    }
  }
}

Daha karmaşık bir senaryo örneği için bkz. uçtan uca örnek yapılandırma.

Ortam

Veri API'sinin yapılandırma dosyası, ASP.NET Core'daki appSettings.json dosyasına benzer şekilde birden çok ortamı desteklemeniz gereken senaryoları destekleyebilir. Çerçeve,üç ortak ortam değeri sağlar; , ve ; ancak seçtiğiniz herhangi bir ortam değerini kullanmayı seçebilirsiniz. Data API builder'ın kullandığı ortam, DAB_ENVIRONMENT ortam değişkeni kullanılarak yapılandırılmalıdır.

Temel yapılandırmayı ve geliştirmeye özgü yapılandırmayı istediğiniz bir örneği düşünün. Bu örnekte iki yapılandırma dosyası gerekir:

	Çevre
dab-config.json	Taban
dab-config.Development.json	Gelişme

Geliştirmeye özgü yapılandırmayı kullanmak için DAB_ENVIRONMENT ortam değişkenini Developmentolarak ayarlamanız gerekir.

Ortama özgü yapılandırma dosyaları, temel yapılandırma dosyasındaki özellik değerlerini geçersiz kılar. Bu örnekte, connection-string değeri her iki dosyada da ayarlanırsa, *.Development.json dosyasındaki değer kullanılır.

Her iki dosyada da bu değerin nerede belirtildiğine (veya belirtilmediğinde) bağlı olarak hangi değerin kullanıldığını daha iyi anlamak için bu matrise bakın.

	temel yapılandırma belirtilen	Temel yapılandırma belirtilmemiş
geçerli ortam yapılandırmasında belirtilen	Geçerli ortam	Geçerli ortam
Geçerli ortam yapılandırma belirtilmemiş	Taban	Hiç kimse

Birden çok yapılandırma dosyası kullanma örneği için bkz. ortamlarla Veri API oluşturucusu kullanma.

Yapılandırma özellikleri

Bu bölüm, bir yapılandırma dosyası için kullanılabilen tüm olası yapılandırma özelliklerini içerir.

Şema

GEREKLI: ✔️ Evet

Her yapılandırma dosyası bir $schema özelliğiyle başlar ve doğrulama için JSON şeması belirtir.

Biçim

{
  "$schema": "<string>"
}

Örnekler

Şema dosyaları, doğru sürümü veya en son kullanılabilir şemayı kullandığınızdan emin olarak belirli URL'lerde 0.3.7-alpha sürümler için kullanılabilir.

https://github.com/Azure/data-api-builder/releases/download/<VERSION>-<suffix>/dab.draft.schema.json

VERSION-suffix istediğiniz sürümle değiştirin.

https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json

Şemanın en son sürümü https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.jsonher zaman kullanılabilir.

Geçerli şema değerlerine birkaç örnek aşağıda verilmiştir.

Sürüm	URI	Tarif
0.3.7-alfa	`https://github.com/Azure/data-api-builder/releases/download/v0.3.7-alpha/dab.draft.schema.json`	Aracın alfa sürümünden yapılandırma şemasını kullanır.
0.10.23	`https://github.com/Azure/data-api-builder/releases/download/v0.10.23/dab.draft.schema.json`	Aracın kararlı bir sürümü için yapılandırma şemasını kullanır.
Sonuncu	`https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json`	Yapılandırma şemasının en son sürümünü kullanır.

Not

Veri API oluşturucusunun 0.3.7-alpha önceki sürümleri farklı bir şema URI'sine sahip olabilir.

Veri kaynağı

GEREKLI: ✔️ Evet

data-source bölümü, veritabanını ve bağlantı dizesi aracılığıyla veritabanına erişimi tanımlar. Ayrıca veritabanı seçeneklerini tanımlar. data-source özelliği, yedekleme veritabanına bağlanmak için gereken kimlik bilgilerini yapılandırmaktadır. data-source bölümünde hem database-type hem de connection-stringbelirterek arka uç veritabanı bağlantısı özetlenmiştir.

Biçim

{
  "data-source": {
    "database-type": "...",
    "connection-string": "your-connection-string",
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": "your-cosmosdb-database-name", 
      "container": "your-cosmosdb-container-name",
      "schema": "path-to-your-graphql-schema-file"
    }
  }
}

Özellikler

	Gerekli	Tür
`database-type`	✔️ Evet	sabit listesi dizesi
`connection-string`	✔️ Evet	dizgi
`options`	❌ Hayır	nesne

Veritabanı türü

GEREKLI: ✔️ Evet

Veri kaynağı olarak kullanılacak veritabanı türünü belirtmek için kullanılan bir sabit listesi dizesi.

Biçim

{
  "data-source"{
    "database-type": "<enum-string>"
  }
}

Değer

type özelliği arka uç veritabanının türünü gösterir.

Tür	Tarif	En Düşük Sürüm
`mssql`	Azure SQL Veritabanı	Yok
`mssql`	Azure SQL MI	Yok
`mssql`	SQL Server	SQL 2016
`sqldw`	Azure SQL Veri Ambarı	Yok
`postgresql`	PostgreSQL	v11
`mysql`	MySQL	v8
`cosmosdb_nosql`	NoSQL için Azure Cosmos DB	Yok
`cosmosdb_postgresql`	PostgreSQL için Azure Cosmos DB	Yok

Bağlantı dizesi

GEREKLI: ✔️ Evet

dizesi, hedef veritabanı hizmetine bağlanmak için geçerli bir bağlantı dizesi içeren değeridir. Arka uç veritabanına bağlanmak için ADO.NET bağlantı dizesi. Daha fazla bilgi için bkz.bağlantı dizelerini ADO.NET.

Biçim

{
  "data-source"{
    "connection-string": "<string>"
  }
}

Bağlantı dayanıklılığı

Veri API oluşturucusu, geçici hatalar algıladıktan sonra veritabanı isteklerini otomatik olarak yeniden denenir. Yeniden deneme mantığı, en fazla yeniden deneme sayısının beşolduğu Üstel Geri Alma stratejisini izler. Sonraki istekler bu formül kullanılarak hesaplandıktan sonra yeniden deneme geri alma süresi (geçerli yeniden deneme girişiminin rolduğu varsayılarak):

$r^2$

Bu formülü kullanarak, her yeniden deneme denemesinin süresini saniyeler içinde hesaplayabilirsiniz.

	Saniye
İlk	`2`
saniye	`4`
Üçüncü	`8`
Dördüncü	`16`
beşinci	`32`

Azure SQL ve SQL Server

Veri API oluşturucusu, yapılandırma dosyasında sağladığınız bağlantı dizesini kullanarak Azure SQL veya SQL Server'a bağlanmak için SqlClient kitaplığını kullanır. Desteklenen tüm bağlantı dizesi seçeneklerinin listesini burada bulabilirsiniz: SqlConnection.ConnectionString Özelliği.

Veri API oluşturucusu, Yönetilen Hizmet Kimliklerini (MSI) kullanarak hedef veritabanına da bağlanabilir. Azure.Identity kitaplığında tanımlanan DefaultAzureCredential, bağlantı dizenizde bir kullanıcı adı veya parola belirtmediğinizde bilinen kimlikleri kullanarak bağlanmak için kullanılır. Daha fazla bilgi için bkz. örnekler.

Örnekler

Bağlantı dizesi için kullanılan değer büyük ölçüde senaryonuzda kullanılan veritabanı hizmetine bağlıdır. Bağlantı dizesini her zaman bir ortam değişkeninde depolamayı ve @env() işlevini kullanarak bu dizeye erişmeyi seçebilirsiniz.

	Değer	Tarif
Azure SQL Veritabanı dize değeri kullanma	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;`	Azure SQL Veritabanı hesabına bağlantı dizesi. Daha fazla bilgi için bkz.Azure SQL Veritabanı bağlantı dizelerini .
PostgreSQL için Azure Veritabanı dize değeri kullanma	`Server=<server-address>;Database=<name-of-database>;Port=5432;User Id=<username>;Password=<password>;Ssl Mode=Require;`	PostgreSQL için Azure Veritabanı hesabına bağlantı dizesi. Daha fazla bilgi için bkz.PostgreSQL için Azure Veritabanı bağlantı dizelerini .
NoSQL için Azure Cosmos DB dize değeri kullanma	`AccountEndpoint=<endpoint>;AccountKey=<key>;`	NoSQL için Azure Cosmos DB hesabına bağlantı dizesi. Daha fazla bilgi için bkz.NoSQL için Azure Cosmos DB bağlantı dizelerini .
MySQL için Azure Veritabanı dize değeri kullanma	`Server=<server-address>;Database=<name-of-database>;User ID=<username>;Password=<password>;Sslmode=Required;SslCa=<path-to-certificate>;`	MySQL için Azure Veritabanı hesabına bağlantı dizesi. Daha fazla bilgi için bkz.MySQL için Azure Veritabanı bağlantı dizelerini .
access ortam değişkeni	`@env('database-connection-string')`	Yerel makineden bir ortam değişkenine erişin. Bu örnekte, `database-connection-string` ortam değişkenine başvurulur.

Bahşiş

En iyi yöntem olarak, hassas bilgileri yapılandırma dosyanızda depolamaktan kaçının. Mümkün olduğunda ortam değişkenlerine başvurmak için @env() kullanın. Daha fazla bilgi için bkz. @env() işlevi.

Bu örnekler yalnızca her veritabanı türünün nasıl yapılandırılabileceğini gösterir. Senaryonuz benzersiz olabilir, ancak bu örnek iyi bir başlangıç noktasıdır. myserver, myDataBase, myloginve myPassword gibi yer tutucuları ortamınıza özgü gerçek değerlerle değiştirin.

mssql
```
"data-source": {
  "database-type": "mssql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "set-session-context": true
  }
}
```
- Tipik bağlantı dizesi biçimi: "Server=tcp:myserver.database.windows.net,1433;Initial Catalog=myDataBase;Persist Security Info=False;User ID=mylogin;Password=myPassword;MultipleActiveResultSets=False;Encrypt=True;TrustServerCertificate=False;Connection Timeout=30;"
postgresql
```
"data-source": {
  "database-type": "postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- Tipik bağlantı dizesi biçimi: "Host=myserver.postgres.database.azure.com;Database=myDataBase;Username=mylogin@myserver;Password=myPassword;"
mysql
```
"data-source": {
  "database-type": "mysql",
  "connection-string": "$env('my-connection-string')"
}
```
- Tipik bağlantı dizesi biçimi: "Server=myserver.mysql.database.azure.com;Database=myDataBase;Uid=mylogin@myserver;Pwd=myPassword;"

cosmosdb_nosql

"data-source": {
  "database-type": "cosmosdb_nosql",
  "connection-string": "$env('my-connection-string')",
  "options": {
    "database": "Your_CosmosDB_Database_Name",
    "container": "Your_CosmosDB_Container_Name",
    "schema": "Path_to_Your_GraphQL_Schema_File"
  }
}

Tipik bağlantı dizesi biçimi: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

cosmosdb_postgresql
```
"data-source": {
  "database-type": "cosmosdb_postgresql",
  "connection-string": "$env('my-connection-string')"
}
```
- Tipik bağlantı dizesi biçimi: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Not

database, containerve schema gibi belirtilen "seçenekler", PostgreSQL API'sine değil Azure Cosmos DB'nin NoSQL API'sine özeldir. PostgreSQL API'sini kullanan Azure Cosmos DB için "seçenekler" NoSQL kurulumunda olduğu gibi database, containerveya schema içermez.

Seçenekler

GEREKLI: ❌ Hayır

Belirli veritabanı bağlantıları için ek anahtar-değer parametrelerinin isteğe bağlı bölümü.

Biçim

{
  "data-source"{
    "options": {
        "<key>": "<value>"
    }
  }
}

Örnekler

options bölümünün gerekli olup olmadığı büyük ölçüde kullanılan veritabanı hizmetine bağlıdır.

	Değer	Tarif
Azure SQL veya SQL Server'da `SESSION_CONTEXT` etkinleştirme	`"set-session-context": false`	Azure SQL ve SQL Server için Veri API oluşturucusu, kullanıcı tarafından belirtilen meta verileri temel alınan veritabanına göndermek için `SESSION_CONTEXT` yararlanabilir. Bu meta veriler, erişim belirtecinde bulunan talepler nedeniyle Veri API'sini oluşturucusunun kullanımına sunulur. `SESSION_CONTEXT` verileri, bu bağlantı kapatılana kadar veritabanı bağlantısı sırasında veritabanı tarafından kullanılabilir. Daha fazla bilgi için bkz. oturum bağlamı.

{
  "data-source"{
    "options": {
        "set-session-context": false
    }
  }
}

Veri kaynağı dosyaları

GEREKLI: ❌ Hayır

Bu özellik, ek veritabanlarına başvuran çalışma zamanı yapılandırma dosyalarının adlarını içerir.

Biçim

{
  "data-source-files": ["<string-array>"]
}

Yapılandırma dosyasıyla ilgili dikkat edilmesi gerekenler

Her yapılandırma dosyasındaki data-source özelliği gereklidir.
Her yapılandırma dosyasındaki entities özelliği gereklidir.
Yalnızca en üst düzey yapılandırma dosyası runtime ayarı kullanılır.
Alt düzey yapılandırma dosyaları da alt dosyaları tanımlayabilir.
Yapılandırma dosyaları alt klasörlere istenildiği gibi yerleştirilebilir.
Varlık adları tüm yapılandırma dosyalarında benzersiz olmalıdır.
Yapılandırma dosyaları arasındaki ilişkiler desteklenmez.

Bilinen sorunlar

Şu anda alt yapılandırma dosyaları yalnızca GraphQL'de desteklenmektedir.
Şu anda alt yapılandırma dosyaları ortam değişkenlerini desteklememektedir.

Örnekler

{
  "data-source-files": ["dab-config-two.json", "dab-config-three.json"]
}

Kullanımdaysa başvuru alt klasörleri:

{
  "data-source-files": ["myfolder/dab-config-two.json"]
}

Çalışma zamanı

GEREKLI: ❌ Hayır

runtime bölümünde, kullanıma sunulan tüm varlıklar için çalışma zamanı davranışını ve ayarlarını etkileyen seçenekler özetlenmiştir.

Biçim

{
  "runtime": {
    "rest": {
      "path": "/api" (default),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": "/graphql" (default),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
    },
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  },
  "cache": {
    "enabled": <true> | <false> (default),
    "ttl-seconds": <integer; default: 5>
  },
  "pagination": {
    "max-page-size": -1, <integer; default: 100000>,
    "default-page-size": -1 | <integer; default: 100>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": "<connection-string>",
      "enabled": <true> | <false> (default)
    }
  }
}

Özellikler

	Gerekli	Tür
`rest`	❌ Hayır	nesne
`graphql`	❌ Hayır	nesne
`host`	❌ Hayır	nesne
`cache`	❌ Hayır	nesne

Örnekler

Aşağıda, birden çok ortak varsayılan parametrenin belirtildiği bir çalışma zamanı bölümü örneği verilmiştir.

{
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/api",
      "request-body-strict": true
    },
    "graphql": {
      "enabled": true,
      "path": "/graphql",
      "allow-introspection": true
    },
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": [
          "*"
        ]
      },
      "authentication": {
        "provider": "StaticWebApps",
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<identity-provider-issuer-uri>"
        }
      }
    },
    "cache": {
      "enabled": true,
      "ttl-seconds": 5
    },
    "pagination": {
      "max-page-size": 100000,
      "default-page-size": 100
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (çalışma zamanı)

GEREKLI: ❌ Hayır

Bu nesne GraphQL'in etkinleştirilip etkinleştirilmediğini ve varlığı bir GraphQL türü olarak kullanıma açmak için kullanılan adı[s] tanımlar. Bu nesne isteğe bağlıdır ve yalnızca varsayılan ad veya ayarlar yeterli değilse kullanılır. Bu bölümde GraphQL uç noktasının genel ayarları özetlenmiştir.

Biçim

{
  "runtime": {
    "graphql": {
      "path": "/graphql" (default),
      "enabled": <true> (default) | <false>,
      "allow-introspection": <true> (default) | <false>
      "multiple-mutations": <object>
    }
  }
}

Özellikler

	Gerekli	Tür
`enabled`	❌ Hayır	Boolean
`path`	❌ Hayır	dizgi
`allow-introspection`	❌ Hayır	Boolean
`multiple-mutations`	❌ Hayır	nesne

Etkin (GraphQL çalışma zamanı)

GEREKLI: ❌ Hayır

GraphQL uç noktalarının genel olarak etkinleştirilip etkinleştirilmeymeyeceğini veya devre dışı bırakılıp bırakılmayacağını tanımlar. Genel olarak devre dışı bırakılırsa, tek tek varlık ayarlarından bağımsız olarak GraphQL istekleri aracılığıyla hiçbir varlığa erişilemez.

Biçim

{
  "runtime": {
    "graphql": {
      "enabled": "<boolean>"
    }
  }
}

Örnekler

Bu örnekte GraphQL uç noktası tüm varlıklar için devre dışı bırakılmıştır.

{
  "runtime": {
    "graphql": {
      "enabled": false
    }
  }
}

Yol (GraphQL çalışma zamanı)

GEREKLI: ❌ Hayır

GraphQL uç noktasının kullanılabilir hale getirildiği URL yolunu tanımlar. Örneğin, bu parametre /graphqlolarak ayarlanırsa GraphQL uç noktası /graphqlolarak kullanıma sunulur. Varsayılan olarak, yol /graphql.

Önemli

Bu özellik için alt yollara izin verilmiyor. GraphQL uç noktası için özelleştirilmiş yol değeri şu anda kullanılamıyor.

Biçim

{
  "runtime": {
    "graphql": {
      "path": "<string>"
    }
  }
}

Örnekler

Bu örnekte, kök GraphQL URI'si /query.

{
  "runtime": {
    "graphql": {
      "path": "/query"
    }
  }
}

İçe aktarmaya izin ver (GraphQL çalışma zamanı)

GEREKLI: ❌ Hayır

Bu Boole bayrağı, GraphQL uç noktasında şema içgörü sorguları gerçekleştirme özelliğini denetler. İçe aktarmayı etkinleştirmek, istemcilerin kullanılabilir veri türleri, gerçekleştirebilecekleri sorgu türleri ve kullanılabilir mutasyonlar hakkında bilgi için şemayı sorgulamasına olanak tanır.

Bu özellik geliştirme sırasında GraphQL API'sinin yapısını anlamak ve otomatik olarak sorgu oluşturan araçlar için kullanışlıdır. Ancak üretim ortamlarında API'nin şema ayrıntılarının gizlenip güvenliğin artırılması devre dışı bırakılabilir. Varsayılan olarak introspection etkindir ve GraphQL şemasının hemen ve kapsamlı bir şekilde keşfine olanak sağlar.

Biçim

{
  "runtime": {
    "graphql": {
      "allow-introspection": "<boolean>"
    }
  }
}

Örnekler

Bu örnekte iç gözlem devre dışı bırakılmıştır.

{
  "runtime": {
    "graphql": {
      "allow-introspection": false
    }
  }
}

Birden çok mutasyon (GraphQL çalışma zamanı)

GEREKLI: ❌ Hayır

GraphQL çalışma zamanı için birden çok mutasyon işleminin tümünü yapılandırıyor.

Not

Varsayılan olarak, birden çok mutasyon etkinleştirilmez ve açıkça etkinleştirilecek şekilde yapılandırılması gerekir.

Biçim

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": <object>
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`create`	❌ Hayır	nesne

Birden çok mutasyon - oluşturma (GraphQL çalışma zamanı)

GEREKLI: ❌ Hayır

GraphQL çalışma zamanı için birden çok oluşturma işlemi yapılandırılır.

Biçim

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": <false> (default) | <true>
        }
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`enabled`	✔️ Evet	Boolean

Örnekler

Bu örnekte, GraphQL çalışma zamanı için birden çok mutasyon etkinleştirilmiştir. Özellikle, birden çok oluşturma işlemi, runtime.graphql.multiple-mutations.create.enabled özelliği için true değeri belirtilerek etkinleştirilir.

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  }
}

REST (çalışma zamanı)

GEREKLI: ❌ Hayır

Bu bölümde REST uç noktalarının genel ayarları özetlenir. Bu ayarlar tüm varlıklar için varsayılan olarak çalışır, ancak ilgili yapılandırmalarında varlık başına temelinde geçersiz kılınabilir.

Biçim

{
  "runtime": {
    "rest": {
      "path": "/api" (default),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    ...
  }
}

Özellikler

	Gerekli	Tür
`enabled`	❌ Hayır	Boolean
`path`	❌ Hayır	dizgi
`request-body-strict`	❌ Hayır	Boolean

Etkin (REST çalışma zamanı)

GEREKLI: ❌ Hayır

REST uç noktalarının genel kullanılabilirliğini belirleyen Boole bayrağı. Devre dışı bırakılırsa, varlıklara tek tek varlık ayarlarından bağımsız olarak REST aracılığıyla erişemezsiniz.

Biçim

{
  "runtime": {
    "rest": {
      "enabled": "<boolean>"
    }
  }
}

Örnekler

Bu örnekte REST API uç noktası tüm varlıklar için devre dışı bırakılmıştır.

{
  "runtime": {
    "rest": {
      "enabled": false
    }
  }
}

Yol (REST çalışma zamanı)

GEREKLI: ❌ Hayır

Kullanıma sunulan tüm REST uç noktalarına erişmek için URL yolunu ayarlar. Örneğin, path/api olarak ayarlanması, REST uç noktasının /api/<entity>'de erişilebilir olmasını sağlar. Alt yollara izin verilmez. Bu alan isteğe bağlıdır ve varsayılan olarak /api.

Not

Statik Web Apps (önizleme) kullanarak Veri API'si oluşturucusu dağıtılırken, Azure hizmeti url'ye otomatik olarak ek alt yol /data-api ekler. Bu davranış, mevcut Statik Web Uygulaması özellikleriyle uyumluluğu sağlar. Sonuçta elde edilen uç nokta /data-api/api/<entity>olacaktır. Bu yalnızca Statik Web Uygulamaları ile ilgilidir.

Önemli

Bu özellik için alt yollara izin verilmiyor.

Biçim

{
  "runtime": {
    "rest": {
      "path": "<string>"
    }
  }
}

Örnekler

Bu örnekte kök REST API URI'sinin /data.

{
  "runtime": {
    "rest": {
      "path": "/data"
    }
  }
}

Bahşiş

bir Author varlığı tanımlarsanız, bu varlığın uç noktası /data/Authorolacaktır.

İstek gövdesi katı (REST çalışma zamanı)

GEREKLI: ❌ Hayır

Bu boole bayrağı, REST mutasyonu işlemi için istek gövdesinin gereksiz alanlar içerip içeremeyeceğini belirler. Varsayılan olarak değer true'dur; başka bir deyişle istek gövdesindeki ek alanlar BadRequest özel durumla sonuçlanır. Ancak, bu bayrağı false olarak ayarlamak, kullanıcıların istek gövdesine yoksayılan ek alanlar eklemesine olanak tanır. İstek gövdesi GET işlemleri için her zaman yoksayıldığı için bu bayrağın REST sorgusu (GET) isteklerini etkilemediğini unutmayın.

Not

Bu bayrak, REST API uç noktasına yönelik HTTP GET isteklerini etkilemez. get işlemleri için istek gövdesi her zaman yoksayılır.

Biçim

{
  "runtime": {
    "rest": {
      "request-body-strict": "<boolean>"
    }
  }
}

Örnekler

Bu örnekte, katı istek gövdesi doğrulaması devre dışı bırakılmıştır.

{
  "runtime": {
    "rest": {
      "request-body-strict": false
    }
  }
}

Konak (çalışma zamanı)

GEREKLI: ❌ Hayır

Çalışma zamanı yapılandırmasındaki host bölümü, Veri API oluşturucusunun işletim ortamı için çok önemli ayarlar sağlar. Bu ayarlar işlem modlarını, CORS yapılandırmasını ve kimlik doğrulama ayrıntılarını içerir.

Biçim

{
  "runtime": {
    ...
    "host": {
      "mode": "production" (default) | "development",
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
  ...
}

Özellikler

	Gerekli	Tür
`mode`	❌ Hayır	sabit listesi dizesi
`cors`	❌ Hayır	nesne
`authentication`	❌ Hayır	nesne

Örnekler

Aşağıda geliştirme barındırma için yapılandırılmış bir çalışma zamanı örneği verilmiştir.

{
  "runtime": {
    "host": {
      "mode": "development",
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      },
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Mod (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

Veri API'sinin oluşturucu altyapısının development veya production modunda çalıştırılması gerekip gerekmediğini tanımlar. Varsayılan değer production.

Genellikle temel alınan veritabanı hataları, geliştirme aşamasında çalışırken günlüklerin varsayılan ayrıntı düzeyi Debug ayarlanarak ayrıntılı olarak gösterilir. Üretimde günlüklerin ayrıntı düzeyi Errorolarak ayarlanır.

Bahşiş

Varsayılan günlük düzeyi dab start --LogLevel <level-of-detail>kullanılarak daha fazla geçersiz kılınabilir. Daha fazla bilgi için bkz.komut satırı arabirimi (CLI) başvurusu.

Biçim

{
  "runtime": {
    "host": {
      "mode": "<enum-string>"
    }
  }
}

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tarif
`production`	Azure'da üretim ortamında barındırırken kullanma
`development`	Yerel makinede geliştirme aşamasında kullanma

CORS (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

Veri API oluşturucusu altyapı konağı için çıkış noktaları arası kaynak paylaşımı (CORS) ayarları.

Biçim

{
  "runtime": {
    "host": {
      "cors": "<object>"
    }
  }
}

Özellikler

	Gerekli	Tür
`allow-credentials`	❌ Hayır	Boolean
`origins`	❌ Hayır	dize dizisi

Kimlik bilgilerine izin ver (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

True ise, Access-Control-Allow-Credentials CORS üst bilgisini ayarlar. Varsayılan olarak, değeri false.

Not

Access-Control-Allow-Credentials CORS üst bilgisinde daha fazla bilgi için bkz. MDN Web Docs CORS başvurusu.

Biçim

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": "<boolean>",
      }
    }
  }
}

Origins (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

CORS için izin verilen çıkış noktalarının listesini içeren bir dizi ayarlar. Bu ayar, tüm kaynaklar için * joker karaktere izin verir.

Biçim

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<string-array>"]
      }
    }
  }
}

Örnekler

Tüm kaynaklardan kimlik bilgileri olmadan CORS'ye izin veren bir konak örneği aşağıda verilmiştir.

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": false,
        "origins": ["*"]
      }
    }
  }
}

Kimlik doğrulaması (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

Veri API oluşturucu konağı için kimlik doğrulamasını yapılandırılır.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "<enum-string>",
        "jwt": "<object>"
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`provider`	❌ Hayır	sabit listesi dizesi
`jwt`	❌ Hayır	nesne

Sağlayıcı (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

host yapılandırmasındaki authentication.provider ayarı, Veri API oluşturucusu tarafından kullanılan kimlik doğrulama yöntemini tanımlar. API'nin kaynaklarına erişmeye çalışan kullanıcıların veya hizmetlerin kimliğini nasıl doğruladığını belirler. Bu ayar, farklı ortamlara ve güvenlik gereksinimlerine göre uyarlanmış çeşitli kimlik doğrulama mekanizmalarını destekleyerek dağıtım ve tümleştirme esnekliği sağlar.

Sağlayıcı	Tarif
`StaticWebApps` (varsayılan)	Veri API'sinin oluşturucusunun yalnızca Statik Web Apps ortamında çalışırken mevcut olan bir HTTP üst bilgileri kümesini aramasını sağlar.
`AppService`	Çalışma zamanı, AppService Kimlik Doğrulaması etkin ve yapılandırılmış (EasyAuth) ile Azure AppService'te barındırıldığında.
`AzureAd`	Microsoft Entra Identity'in, Veri API oluşturucusunun ("Sunucu Uygulaması") gönderilen bir isteğin kimliğini doğru edebilmesi için yapılandırılması gerekir. Daha fazla bilgi için bkz. Microsoft Entra ID kimlik doğrulaması.
`Simulator`	Data API builder altyapısına tüm isteklerin kimliği doğrulanmış olarak davranmasını isteyen yapılandırılabilir bir kimlik doğrulama sağlayıcısı. Daha fazla bilgi için bkz. yerel kimlik doğrulaması.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "<enum-string>",
      }
    }
  }
}

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tarif
`StaticWebApps`	Azure Static Web Apps
`AppService`	Azure App Service
`AzureAD`	Microsoft Entra ID
`Simulator`	Simülatörü

JSON Web Belirteçleri (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

Kimlik doğrulama sağlayıcısı AzureAD (Microsoft Entra Id) olarak ayarlandıysa, JSOn Web Belirteçleri (JWT) belirtecinin hedef kitlesini ve verenleri belirtmek için bu bölüm gereklidir. Bu veriler, belirteçleri Microsoft Entra kiracınızda doğrulamak için kullanılır.

Kimlik doğrulama sağlayıcısı Microsoft Entra Id için AzureAD ise gereklidir. Bu bölüm, kimlik doğrulaması için hedeflenen AzureAD kiracısına karşı alınan JWT belirtecini doğrulamak için audience ve issuer belirtmelidir.

Ayar	Tarif
seyirci	Belirtecin hedeflenen alıcısını tanımlar; genellikle uygulamanın tanımlayıcısı Microsoft Entra Identity'e (veya kimlik sağlayıcınıza) kaydedilir ve belirtecin uygulamanız için gerçekten verildiğinden emin olur.
Veren	JWT'yi veren belirteç hizmeti olan veren yetkilinin URL'sini belirtir. Bu URL, belirtecin kaynağını doğrulayarak JWT'nin alındığı kimlik sağlayıcısının veren URL'si ile eşleşmelidir.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`audience`	❌ Hayır	dizgi
`issuer`	❌ Hayır	dizgi

Örnekler

Veri API oluşturucusu (DAB), Microsoft Entra Identity ve özel JSON Web Belirteci (JWT) sunucularıyla tümleştirilerek esnek kimlik doğrulama desteği sunar. Bu görüntüde JWT Sunucusu, başarılı bir oturum açma sırasında istemcilere JWT belirteçleri veren kimlik doğrulama hizmetini temsil eder. İstemci daha sonra belirteci DAB'ye geçirir ve bu da taleplerini ve özelliklerini sorgulayabilir.

Veri API'sinin oluşturucusunda JSON web belirteçleri diyagramı desteği.

Aşağıda, çözümünüzde yapabileceğiniz çeşitli mimari seçimlere göre host özelliğine örnekler verilmiştir.

Azure Static Web Apps

{
 "host": {
  "mode": "development",
  "cors": {
   "origins": ["https://dev.example.com"],
   "credentials": true
  },
  "authentication": {
   "provider": "StaticWebApps"
  }
 }
}

StaticWebAppsile Veri API oluşturucusu, Azure Static Web Apps'in isteğin kimliğini doğrulamasını bekler ve X-MS-CLIENT-PRINCIPAL HTTP üst bilgisi bulunur.

Azure App Service

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": false
  },
  "authentication": {
   "provider": "AppService",
   "jwt": {
    "audience": "9e7d452b-7e23-4300-8053-55fbf243b673",
    "issuer": "https://example-appservice-auth.com"
   }
  }
 }
}

Kimlik doğrulaması, erişim belirtecinin verilebildiği desteklenen bir kimlik sağlayıcısına temsilci olarak atanır. Alınan erişim belirteci, Veri API oluşturucusunda gelen isteklere eklenmelidir. Veri API oluşturucusu daha sonra sunulan erişim belirteçlerini doğrulayarak Veri API'sinin oluşturucusunun belirtecin hedef kitlesi olduğundan emin olur.

Microsoft Entra ID

{
 "host": {
  "mode": "production",
  "cors": {
   "origins": [ "https://api.example.com" ],
   "credentials": true
  },
  "authentication": {
   "provider": "AzureAD",
   "jwt": {
    "audience": "c123d456-a789-0abc-a12b-3c4d56e78f90",
    "issuer": "https://login.microsoftonline.com/98765f43-21ba-400c-a5de-1f2a3d4e5f6a/v2.0"
   }
  }
 }
}

Simülatör (Yalnızca geliştirme)

{
 "host": {
  "mode": "development",
  "authentication": {
   "provider": "Simulator"
  }
 }
}

İzleyici (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

JWT belirtecinin hedef kitlesi.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<string>",
        }
      }
    }
  }
}

Veren (Konak çalışma zamanı)

GEREKLI: ❌ Hayır

JWT belirteci için veren.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<string>"
        }
      }
    }
  }
}

Sayfalandırma (çalışma zamanı)

GEREKLI: ❌ Hayır

Sonuç sınırlarını yapılandırıyor.

Biçim

{
  "runtime": {
    "pagination": {
      "max-page-size": -1, 
      "default-page-size": -1 
    }
  }
}

Özellikler

	Gerekli	Tür	Temerrüt
`max-page-size`	❌ Hayır	tam sayı	100,000
`default-page-size`	❌ Hayır	tam sayı	100

Örnek

{
  "runtime": {
    "pagination": {
      "max-page-size": 100000,
      "default-page-size": 1
    }
  }
}

REST sayfalandırma örneği

Örnekte REST GET https://localhost:5001/api/booksverdiysek, sayfa boyutu varsayılan olarak 1 olduğundan elde edilen JSON, value dizisine bir kayıt ekler. Örnek sonuçlar, Sonraki bir sayfa mevcut olduğunda Veri API'sinin oluşturucusunun sonuçlara nasıl nextLink ekleyeceğini gösterir.

{
  "value": [
    {
      "id": 1000,
      "title": "Prelude to Foundation",
      "year": 1988,
      "pages": 403,
      "series_id": 10000
    }
  ],
  "nextLink": "https://localhost:5001/api/books?$after=W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
}

$after seçeneğinin uç noktayı sorgulamak için kullanılan URL'ye eklendiğine dikkat edin. Bu özel değer, geçerli sayfadaki son kaydı dahili olarak gösterir. sağlanan dizeyi $after değeri olarak kullanmak otomatik olarak sonraki veri sayfasını döndürür.

Not

Temel alınan tablo verilerinin sorgular arasında değişmesi mümkündür. Bu bir hataya neden olmaz; ancak, Veri API'sinin oluşturucusunun neden sayfa numarası kavramına sahip olmadığını gösterir. Sonraki çağrılar doğru sonraki sayfayı döndürür, ancak veri değişiklikleri nedeniyle sayfa numarası değişmiş olabilir. Bu şekilde ,sayı sonraki sayfa değil, veribir sonraki sayfasıdır.

GraphQL sayfalandırma örneği

Örnekte bir GraphQL sorgusu verirsek sayfalandırmayı kullanmak için hasNextPage ve endCursor eklemeliyiz. Bu gereksinimin nedeni REST uç noktalarının yüklerinin yapısını belirlemesi, ancak tüketicinin sorgusunun GraphQL yüklerinin yapısını belirlemesidir. Bu değerlerle veya bu değerler olmadan sonuçlar yine de varsayılan sayfa boyutuyla sınırlıdır. Sorgu şöyle görünür:

query {
  books {
    items {
      id,
      title,
      year,
      pages,
      series_id
    }
    hasNextPage
    endCursor
  }
}

GraphQL sonuçlarımız, daha fazla sayfa getirmek için kullanılan hasNextPage ve endCursoriçerir.

{
  "data": {
    "books": {
      "items": [
        {
          "id": 1000,
          "title": "Prelude to Foundation",
          "year": 1988,
          "pages": 403,
          "series_id": 10000
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI=="
    }
  }
}

Sonraki GraphQL sorgusu, aşağıdaki şekilde imleci after değişkeninin değeri olarak içerir:

query {
  books(after: "W3siRW50aXR5TmFtZSI6ImJvb2tzIiwiRmllbGROYW1lI==") {
    items {
      id
      title
      year
      pages
      series_id
    }
    hasNextPage
    endCursor
  }
}

Sayfa boyutunu değiştirmek için $limit veya first kullanma.

Hem REST hem de GraphQL sırasıyla bir $limit veya first değişkeni içerebilir. limit amacı, belirli bir sorgunun sonuçlarını sınırlamaktır. Ancak, https://{server}/api/books?$limit=10düşünün. varsayılan sayfa boyutu 100 olduğunda limit 10 ise, sonuçlar 10 ile sınırlıdır. Ancak, varsayılan sayfa boyutu 100 olduğunda limit 200 ise, sonuçlar varsayılan sayfa boyutundan daha büyük bir değer olan 200 ile sınırlıdır.

İlk değer	Sonuç
`-1`	`max-page-size` ayarının geçerli değeri. `max-page-size` ayarı değeri tüketici tarafından bilinmediğinde `-1` kullanmak kullanışlıdır. Veri API'sinin oluşturucusu, `-1` değerini geçerli `max-page-size`değeriyle değiştirir.
`< max-page-size`	Sonuçlar sağlanan değerle sınırlıdır.
`0`	Geçersiz. Bir özel durum döndürülür.
`< -1`	Geçersiz. Bir özel durum döndürülür.
`> max-page-size`	Geçersiz. Bir özel durum döndürülür.

En büyük sayfa boyutu (Sayfalandırma çalışma zamanı)

GEREKLI: ❌ Hayır

REST veya GraphQL sorgusu tarafından döndürülen en üst düzey kayıt sayısı üst sınırını ayarlar.

İzin verilen değerler

Değer	Sonuç
`-1`	Bu değer varsayılan olarak desteklenen en yüksek değerdir.
`integer`	Herhangi bir pozitif 32 bit tamsayı desteklenir.
`< -1`	Bu desteklenmez.
`= 0`	Bu desteklenmez.

Not

32 bitlik bir tamsayının en büyük değeri 2.147.483.647'dir. Bu büyük bir şey. Uygulamada, giden uç nokta yükünün boyutu için katı bir evrensel sınır yoktur, ancak sunucu yapılandırması, bant genişliği ve zaman aşımı gibi çeşitli faktörler boyutu etkili bir şekilde sınırlayabilir. Veri API'si oluşturucusu senaryonuzu bilmediği için bu ayar her geliştirici tarafından yapılandırmaya açıktır. Varsayılan maksimum 100.000 zaten oldukça agresiftir.

Varsayılan sayfa boyutu (Sayfalandırma çalışma zamanı)

GEREKLI: ❌ Hayır

Sayfalandırma, REST veya GraphQL sorgusu tarafından döndürülen en üst düzey kayıt sayısı olduğunda sayfa boyutunu ayarlar.

İzin verilen değerler

Değer	Sonuç
`-1`	Bu değer varsayılan olarak geçerli `max-page-size` ayarıdır.
`integer`	Geçerli `max-page-size` ayarından küçük pozitif tamsayılar.
`< -1`	Bu desteklenmez.
`= 0`	Bu desteklenmez.

Önbellek (çalışma zamanı)

GEREKLI: ❌ Hayır

Tüm çalışma zamanı için önbelleğe almayı etkinleştirir ve yapılandırr.

Biçim

{
  "runtime": {
    "cache": "<object>"
  }
}

Özellikler

	Gerekli	Tür
`enabled`	❌ Hayır	Boolean
`ttl-seconds`	❌ Hayır	tam sayı

Örnekler

Bu örnekte önbellek etkinleştirilir ve öğelerin süresi 30 saniye sonra dolar.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 30
    }
  }
}

Etkin (Önbellek çalışma zamanı)

GEREKLI: ❌ Hayır

Tüm varlıklar için genel olarak önbelleğe almayı etkinleştirir. varsayılan olarak false.

Biçim

{
  "runtime": {
    "cache":  {
      "enabled": "<boolean>"
    }
  }
}

Örnekler

Bu örnekte önbellek devre dışıdır.

{
  "runtime": {
    "cache": {
      "enabled": false
    }
  }
}

Saniye olarak TTL (Önbellek çalışma zamanı)

GEREKLI: ❌ Hayır

Önbelleğe alınan öğeler için yaşam süresi (TTL) değerini saniyeler içinde yapılandırır. Bu süre geçtikten sonra, öğeler önbellekten otomatik olarak çıkarılır. Varsayılan değer 5 saniyedir.

Biçim

{
  "runtime": {
    "cache":  {
        "ttl-seconds": "<integer>"
    }
  }
}

Örnekler

Bu örnekte önbellek genel olarak etkinleştirilir ve tüm öğelerin süresi 15 saniye sonra dolar.

{
  "runtime": {
    "cache": {
      "enabled": true,
      "ttl-seconds": 15
    }
  }
}

Telemetri (çalışma zamanı)

GEREKLI: ❌ Hayır

Bu özellik, API günlüklerini merkezileştirmek için Application Insights'ı yapılandırmaktadır. daha fazla bilgi edinin.

Varlık

GEREKLI: ✔️ Evet

entities bölümü, veritabanı nesneleriyle ilgili API uç noktaları arasında bir köprü oluşturarak yapılandırma dosyasının çekirdeğini oluşturur. Bu bölüm veritabanı nesnelerini kullanıma sunulan uç noktalara eşler. Bu bölüm, özellik eşleme ve izin tanımını da içerir. Kullanıma sunulan her varlık ayrılmış bir nesnede tanımlanır. Nesnesinin özellik adı, kullanıma sunma varlığın adı olarak kullanılır.

Bu bölüm, özellik eşlemeleri ve izinler de dahil olmak üzere veritabanındaki her varlığın API'de nasıl temsil edilir olduğunu tanımlar. Her varlık kendi alt bölümünde kapsüllenir ve varlığın adı yapılandırma boyunca başvuru için anahtar görevi görür.

Biçim

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": "/entity-path", (default <entity-name>)
        "methods": ["GET", "POST" (default)]
      },
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": "myEntity",
          "plural": "myEntities"
        },
        "operation": "query" | "mutation" (default)
      },
      "source": {
        "object": "database-object-name",
        "type": "view" | "stored-procedure" | "table",
        "key-fields": ["field-name"],
        "parameters": {
          "parameter-name": "parameter-value"
        }
      },
      "mappings": {
        "database-field-name": "field-alias"
      },
      "relationships": {
        "relationship-name": {
          "cardinality": "one" | "many",
          "target.entity": "target-entity-name",
          "source.fields": ["source-field-name"],
          "target.fields": ["target-field-name"],
          "linking.object": "linking-object-name",
          "linking.source.fields": ["linking-source-field-name"],
          "linking.target.fields": ["linking-target-field-name"]
        }
      },
      "permissions": [
        {
          "role": "anonymous | authenticated | custom-role-name",
          "actions": ["create" | "read" | "update" | "delete" | "*"],
          "fields": {
            "include": ["field-name"],
            "exclude": ["field-name"]
          },
          "policy": {
            "database": "<Expression>"
          }
        }
      ]
    }
  }
}

Özellikler

	Gerekli	Tür
`source`	✔️ Evet	nesne
`permissions`	✔️ Evet	dizi
`rest`	❌ Hayır	nesne
`graphql`	❌ Hayır	nesne
`mappings`	❌ Hayır	nesne
`relationships`	❌ Hayır	nesne
`cache`	❌ Hayır	nesne

Örnekler

Örneğin, bu JSON nesnesi Data API builder'a Author adlı bir GraphQL varlığını ve /Author yolu üzerinden erişilebilen bir REST uç noktasını kullanıma sunmasını bildirir. dbo.authors veritabanı tablosu varlığı destekler ve yapılandırma herkesin uç noktaya anonim olarak erişmesine olanak tanır.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

Bu örnekte User varlığı bildirmektedir. Bu ad User, yapılandırma dosyasında varlıklara başvurulan herhangi bir yerde kullanılır. Aksi takdirde varlık adı uç noktalarla ilgili değildir.

{
  "entities": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/books",
        "methods": ["GET", "POST", "PUT"]
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      "source": {
        "object": "BooksTable",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {}
      },
      "mappings": {
        "id": "Id",
        "title": "Title",
        "authorId": "AuthorId"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],
          "fields": {
            "include": ["id", "title"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.authorId"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRoles has 'BookAdmin'"
          }
        }
      ]
    }
  }
}

Kaynak

GEREKLI: ✔️ Evet

{entity}.source yapılandırması, API tarafından kullanıma sunulan varlık ile temel alınan veritabanı nesnesi arasındaki bağlantıyı tanımlamada çok önemlidir. Bu özellik, varlığın temsil ettiği veritabanı tablosunu, görünümünü veya saklı yordamını belirtir ve veri alma ve işleme için doğrudan bağlantı oluşturur.

Varlığın doğrudan tek bir veritabanı tablosuna veya koleksiyonuna eşlendiği basit senaryolar için kaynak özelliğin yalnızca bu veritabanı nesnesinin adına ihtiyacı vardır. Bu basitlik, yaygın kullanım örnekleri için hızlı kurulumu kolaylaştırır.

Biçim

{
  ...
  "entities" {
    "<entity-name>": {
      ...
      "source": {
        "object": "<string>",
        "type": "<view> | <stored-procedure> | <table>",
        "key-fields": [ "<array-of-strings>" ],
        "parameters": {
            "<name>": "<value>",
            "<name>": "<value>"
        }        
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`object`	✔️ Evet	dizgi
`type`	✔️ Evet	sabit listesi dizesi
`parameters`	❌ Hayır	nesne
`key-fields`	❌ Hayır	dize dizisi

Örnekler

Bu örnekte, bir varlığı kaynak tabloyla ilişkilendirmek için en basit yapı gösterilmektedir.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      }
    }
  }
}

Çoka çok ilişkisinin bir ek haritası aşağıdadır.

Birden çok veritabanı tablosu arasındaki çoka çok ilişkisinin diyagramı

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "type": "stored-procedure",
        "object": "GetUserTodos"
      },
      "parameters": {
        "UserId": 0, 
        "Completed": null,
        "CategoryName": null
      },
      "mapping": {
        "Id": "todo_id",
        "Title": "todo_title",
        "Description": "todo_description",
        "Completed": "todo_completed"
      }
    }
  }
}

Saklı yordam tarafından yedeklenen Todo varlığı.
Kaynağın içindeki type özelliği, varlığın eşlendiği kaynak nesne türünü gösteren stored-procedureolarak ayarlanır.
Kaynak içindeki object özelliği, veritabanındaki saklı yordamın adıdır.

Ayrıca bu örnekte , (isteğe bağlı) mapping özelliği "Todo" varlığının yapılandırmasına eklenir. Varlıktaki (Id, Title, Descriptionve Completed) alanların temel alınan veri kaynağındaki veya saklı yordam parametrelerindeki karşılık gelen alanlarla (sırasıyla ,todo_id, todo_title, todo_descriptionve todo_completed) nasıl eşleneceğini belirtir. Bu eşleme, oluşturma/güncelleştirme işlemleri sırasında varlık ile saklı yordam arasında doğru verilerin geçirilmesini sağlar.

Önceki örnekte aşağıdaki SQL yordamı kullanılır.

CREATE PROCEDURE GetUserTodos
    @UserId INT,
    @Completed BIT = NULL,
    @CategoryName NVARCHAR(100) = NULL
AS
BEGIN
    SELECT t.*
    FROM Todo t
    INNER JOIN users_todos ut ON t.id = ut.todo_id
    INNER JOIN Category c ON t.category_id = c.id
    WHERE ut.user_id = @UserId
    AND ISNULL(@Completed, t.completed)
    AND ISNULL(@CategoryName, c.name)
END

@UserId: Varsayılan değer içermeyen zorunlu parametre.
@Completed: İsteğe bağlı parametre. Sağlanırsa, yapılacakları tamamlanma durumlarına göre filtreler.
@CategoryName: İsteğe bağlı parametre. Sağlanırsa, yapılacakları kategori adına göre filtreler.

Aşağıda saklı yordam kullanan güncelleştirmeler için bir örnek verilmiştır.

{
  "entities": {
    "Todo": {
      "type": "stored-procedure",
      "source": {
        "object": "UpsertTodo"
      },
      "method": "POST", // Specify the HTTP method as POST
      "parameters": {
        "Id": 0,
        "Title": null,
        "Description": null,
        "Completed": null
      }
    }
  }
}

Bu örnek, bu varlıkla etkileşime geçmek için HTTP yöntemini açıkça method özelliğini kullanarak POST olarak ayarlar.

CREATE PROCEDURE UpsertTodo
    @Id INT,
    @Title NVARCHAR(100),
    @Description NVARCHAR(255),
    @Completed BIT
AS
BEGIN
    SET NOCOUNT ON;

    MERGE INTO Todo AS target
    USING (VALUES (@Id, @Title, @Description, @Completed)) AS source (Id, Title, Description, Completed)
    ON target.Id = source.Id
    WHEN MATCHED THEN
        UPDATE SET
            Title = source.Title,
            Description = source.Description,
            Completed = source.Completed
    WHEN NOT MATCHED THEN
        INSERT (Id, Title, Description, Completed)
        VALUES (source.Id, source.Title, source.Description, source.Completed);
END;

Nesne

GEREKLI: ✔️ Evet

Kullanılacak veritabanı nesnesinin adı.

Örnekler

Bu örnekte object veritabanındaki dbo.books nesnesine başvurur.

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.books",
        "type": "table"
      }
    }
  }
}

Tür (varlıklar)

GEREKLI: ✔️ Evet

type özelliği varlığın arkasındaki veritabanı nesnesinin türünü tanımlar; bunlar view, tableve stored-procedureiçerir. type özelliği gereklidir ve varsayılan değer yoktur.

Biçim

{
  "entities" {
    "<entity-name>": {
      "type": "<view> | <stored-procedure> | <table>",
      ...
    }
  }
}

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tarif
`table`	Tabloyu temsil eder.
`stored-procedure`	Saklı yordamı temsil eder.
`view`	Bir görünümü temsil eder.

Örnekler

Bu örnekte, type bu kaynağın veritabanındaki bir görünüm olduğunu gösterir. Bu değer, diğer değerlerin (ör. key-fields) gerekli olup olmadığını etkiler.

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

Anahtar alanları

GEREKLI: ❌ Hayır

{entity}.key-fields ayarı, görünümler tarafından yedeklenen varlıklar için gereklidir, böylece Veri API'si oluşturucusu gerekirse tek bir öğeyi nasıl tanımlayıp döndürebileceğini bilir. type key-fieldsolmadan view olarak ayarlanırsa, Veri API'si oluşturucu altyapısı başlatmayı reddeder.

Önemli

Nesne türü bir viewise bu özellik gereklidir. Ayrıca bu özellik, nesne türünün birincil anahtar tanımlanmamış bir table olmasıdır.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "type": "view",
      "key-fields": [ "<field-name>" ]
    }
  }
}

Örnekler

Bu örnekte anahtar alanı olarak belirtilen category_id ile dbo.vw_category_details görünümü kullanılır.

{
  "entities": {
    "Category": {
      "source": {
        "object": "dbo.vw_category_details",
        "type": "view",
        "key-fields": [
          "category_id"
        ]
      }
    }
  }
}

Parametre

GEREKLI: ❌ Hayır

{entity}.parameters ayarı, saklı yordamlar tarafından yedeklenen varlıklar için önemlidir ve geliştiricilerin parametreleri ve varsayılan değerlerini belirtmesini sağlar. Parametreler, bir HTTP isteğinde belirli parametreler sağlanmazsa sistemin önceden tanımlanmış bu değerlere geri dönebilmesini sağlar.

Önemli

Nesne türü bir stored-procedureise bu özellik gereklidir.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "type": "stored-procedure",
      "parameters": {
        "<parameter-name-1>" : "<default-value>",
        "<parameter-name-2>" : "<default-value>",
        "<parameter-name-3>" : "<default-value>"
      }
    }
  }
}

Örnekler

Bu örnek, şu iki parametreyi geçiren dbo.stp_get_bestselling_books saklı yordamı çağırır:

	Değer
`depth`	25
`list`	contoso-best-sellers

{
  "entities": {
    "BestsellingBooks": {
      "source": {
        "object": "dbo.stp_get_bestselling_books",
        "type": "stored-procedure",
        "parameters": {
          "depth": 25,
          "list": "contoso-best-sellers"
        }
      }
    }
  }
}

İzinler

GEREKLI: ✔️ Evet

Bu bölüm, ilgili varlığa kimlerin erişebileceğini ve hangi eylemlere izin verilip verilmeyebileceğini tanımlar. İzinler bu bölümde rol koşullarıyla tanımlanır. Eylemler şunlar gibi tipik CRUD işlemleri olarak tanımlanır: create, read, updateve delete. permissions bölümü, ilgili varlığa kimlerin (roller açısından) erişebileceğini ve hangi eylemleri kullanabileceğini tanımlar. Eylemler her zamanki CRUD işlemleridir: create, read, update, delete.

Biçim

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          ...
          "actions": [
            "create", 
            "read", 
            "update", 
            "delete", 
            "execute"
          ],
        }
      ]
    }
  }
}

Özellikler

	Gerekli	Tür
`role`	✔️ Evet	dizgi
`actions` (dize dizisi) veya `actions` (nesne dizisi)	✔️ Evet	object veya dize dizisi

Örnekler

Bu örnekte, tüm olası eylemlere erişim ile anonim bir rol tanımlanmıştır.

{
  "entities": {
    "Writer": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

Alternatif olarak, joker karakter eylemini tanımlamak için bir nesne kullanılabilir.

{
  "entities": {
    "Editor": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "*"
            }
          ]        
        }
      ]
    }
  }
}

Ayrıca dize ve nesne dizisi eylemlerini karıştırabilir ve eşleştirebilirsiniz.

{
  "entities": {
    "Reviewer": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            },
            "create"
          ]        
        }
      ]
    }
  }
}

Anonim Rol Anonim kullanıcıların secret-fielddışındaki tüm alanları okumasına izin verin. "exclude": ["secret-field"] ile "include": ["*"] kullanımı, anonim kullanıcılardan secret-field etkili bir şekilde gizlerken diğer tüm alanlara erişim sağlar.

Kimliği Doğrulanmış Rol Kimliği doğrulanmış kullanıcıların açıkça id, titleve secret-fieldgibi belirli alanları okumasına ve güncelleştirmesine izin verin, ancak secret-fieldhariç tutarak. excludeönceliğini gösteren secret-field'in açık eklenmesini ve sonraki dışlanmasını gösterir. secret-field hem dahil hem de dışlandığından erişilemez hale gelir ve bu da öncelik alan exclude hedeflenen kuralıyla eşleşir.

Yazar Rolü Yazarlar, dışlama olmadan tüm alanlarda * tüm işlemleri yapabilir. Dosya, boş bir "exclude": [] dizisi olan "include": ["*"] tüm alanlara erişim izni verir, hiçbir alan açıkça dışlanmaz.

Hiçbir şey belirtilmezse bu yapılandırma varsayılanı temsil eder.

"fields": {
  "include": [],
  "exclude": []
}

Etkili bir şekilde şu şekilde aynıdır:

"fields": {
  "include": [ "*" ],
  "exclude": []
}

Ayrıca aşağıdaki kurulumu da göz önünde bulundurun:

"fields": {
  "include": [],
  "exclude": ["*"]
}

Önceki yapılandırma etkin bir şekilde hiçbir alanın dahil olmadığını ("include": [] boş olduğunu, alanlara izin verilmediğini belirtir) ve tüm alanların dışlandığını belirtir ("exclude": ["*"] tüm alanları belirtmek için joker karakter * kullanır).

Pratik Kullanım: Bu tür bir yapılandırma, tüm alanlara erişimi kısıtladığından uyumsuz görünebilir. Ancak, bir rolün verilerine erişmeden varlık oluşturma gibi belirli eylemleri gerçekleştirebileceği senaryolarda kullanılabilir.

Aynı davranış, ancak farklı söz dizimi ile şu şekilde olacaktır:

"fields": {
  "include": ["Id", "Title"],
  "exclude": ["*"]
}

Önceki kurulum, yalnızca Id ve Title alanlarının dahil edilmesi gerektiğini belirtmeye çalışırken, exclude bölümündeki joker karakter * tüm alanların dışlanması gerektiğini de belirtir. Aynı mantığı ifade etmenin başka bir yolu da şu olabilir:

"fields": {
  "include": ["Id", "Title"],
  "exclude": ["Id", "Title"]
}

exclude listesinin include listesinden öncelikli olduğu genel kuralı göz önünde bulundurulduğunda, exclude: ["*"] belirtilmesi genellikle include bölümünde listelenen alanlar bile dahil tüm alanların dışlandığı anlamına gelir. Bu nedenle, dışlama kuralı baskın olduğundan, bu yapılandırma ilk bakışta herhangi bir alanın erişilebilir olmasını engelliyor gibi görünebilir.

ters: Amaç yalnızca ve alanlarına erişim vermekse, yalnızca bölümündeki alanları belirtmek ve joker karakterle kullanmamak daha açık ve daha güvenilirdir. Alternatif olarak, sistemin izin mantığını, tasarımını denetlediğiniz varsayılarak bu tür durumları açıkça karşılayacak şekilde ayarlayabilirsiniz. Mesela:

"fields": {
  "include": ["Id", "Title"],
  "exclude": []
}

Rol

GEREKLI: ✔️ Evet

Tanımlanan iznin uygulandığı rolün adını içeren dize. role dizesi, tanımlı iznin uygulandığı rolün adını içerir.

Roller, bir isteğin yürütülmesi gereken izin bağlamını ayarlar. Çalışma zamanı yapılandırmasında tanımlanan her varlık için, varlığa hem REST hem de GraphQL uç noktalarında nasıl erişilebileceğini belirleyen bir rol kümesi ve ilişkili izinler tanımlayabilirsiniz. Roller ekli değildir. Roller hakkında daha fazla bilgi için bkz. yetkilendirme.

Veri API oluşturucusu istekleri tek bir rol bağlamında değerlendirir:

Rol	Tarif
`anonymous`	Erişim belirteci sunulmaz
`authenticated`	Geçerli bir erişim belirteci sunulur
`<custom-role>`	Geçerli bir erişim belirteci sunulur ve `X-MS-API-ROLE` HTTP üst bilgisi, erişim belirtecinin rol talebine de dahil olan bir kullanıcı rolü belirterek eklenir

Biçim

{
  "entities": {
    "entity-name": {
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | "custom-role",
          "actions": [
            "create",
            "read",
            "update",
            "delete",
            "execute", // only when stored-procedure
            "*"
          ],
          "fields": {
            "include": ["field-name", "field-name"],
            "exclude": ["field-name", "field-name"]
          }
        }
      ]
    }
  }
}

Örnekler

Bu örnek, uç noktada yalnızca read izinlerine sahip reader adlı bir rolü tanımlar.

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "reader",
          "actions": [
            "read"
          ]        
        }
      ]
    }
  }
}

Eylemler (dize dizisi)

GEREKLI: ✔️ Evet

İlişkili rol için izin verilen işlemlerin ayrıntılarını gösteren dize değerleri dizisi. table ve view veritabanı nesneleri için roller, create, read, updateveya delete eylemlerinin herhangi bir bileşimini kullanacak şekilde yapılandırılabilir. Saklı yordamlar için roller yalnızca execute eylemine sahip olabilir. actions dizisi, ilişkili rolde izin verilen eylemlerin ayrıntılarını verir. Varlık bir tablo veya görünüm olduğunda roller, create, read, updatedeleteeylemlerinin bir bileşimiyle yapılandırılabilir.

Eylem	SQL İşlemi
`*`	Yürütme dahil joker karakter
`create`	Bir veya daha fazla satır ekleme
`read`	Bir veya daha fazla satır seçme
`update`	Bir veya daha fazla satırı değiştirme
`delete`	Bir veya daha fazla satırı silme
`execute`	Saklı yordam çalıştırır

Not

Saklı yordamlar için joker karakter (*) eylemi yalnızca execute eylemini içeren bir listeye genişletir. Tablolar ve görünümler için joker eylem, create, read, updateve delete eylemleri içeren bir listeye genişletilir.

Örnekler

Bu örnek, contributoradlı ilk rol için create ve read izinleri verir. auditor adlı ikinci rolün yalnızca delete izinleri vardır.

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            "delete"
          ]        
        },
        {
          "role": "contributor",
          "actions": [
            "read",
            "create"
          ]
        }
      ]
    }
  }
}

İşte başka bir örnek.

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Eylemler (nesne dizisi)

GEREKLI: ✔️ Evet

Not

Biçim

{
  "entities": {
    "<string>": {
      "permissions": [
        {
          "role": "<string>",
          "actions": [
            {
              "action": "<string>",
              "fields": ["<string-array>"],
              "policy": "object"
            }
          ]
        }
      ]
    }
  }
}

Özellikler

	Gerekli	Tür
`action`	✔️ Evet	dizgi
`fields`	❌ Hayır	dize dizisi
`policy`	❌ Hayır	nesne

Örnekler

Bu örnek, auditor rolüne yalnızca read izin verir. auditor rolü yalnızca policy.databaseiçinde tanımlanan koşulu kullanarak belirli verileri okuyabilir. auditor rolü, fields özelliğini kullanarak okuyabileceği veya okuyabileceği alanlarda da sınırlıdır.

{
  "entities": {
    "CheckoutLogs": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_updated"]
              },
              "policy": {
                "database": "@item.LogDepth lt 3"
              }
            }
          ]
        }
      ]
    }
  }
}

Eylem

GEREKLI: ✔️ Evet

Veritabanı nesnesinde izin verilen işlemi belirtir.

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tablo	Görünümler	Saklı Yordamlar	Tarif
`create`	✔️ Evet	✔️ Evet	❌ Hayır	Yeni öğe oluşturma
`read`	✔️ Evet	✔️ Evet	❌ Hayır	Var olan öğeleri puan okuma
`update`	✔️ Evet	✔️ Evet	❌ Hayır	Varolan öğeleri güncelleştirme veya değiştirme
`delete`	✔️ Evet	✔️ Evet	❌ Hayır	Varolan öğeleri kaldırma
`execute`	❌ Hayır	❌ Hayır	✔️ Evet	Programlı işlemleri yürütme

Örnekler

Aşağıda, anonymous kullanıcıların belirli bir saklı yordamı execute ve belirli bir tabloyu read izin verilen bir örnek verilmiştır.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

Alanları

GEREKLI: ❌ Hayır

Veritabanı nesnesi için belirli alanlara erişim izni verilen ayrıntılı belirtimler. Rol yapılandırması, include ve excludeolmak üzere iki iç özelliğe sahip bir nesne türüdür. Bu değerler, fieldsbölümünde hangi veritabanı sütunlarına (alanlar) erişim izni verileceği ayrıntılı olarak tanımlanmasını destekler.

Biçim

{
  ...
  "entities": {
    "<entity-name>": {
      ...
      "permissions": [
        {
          {
            ...
            "fields": {
              "include": ["<field-name>"],
              "exclude": ["<field-name>"]
            }
          }
        }
      ]
    }
  }
}

Örnekler

Bu örnekte, anonymous rolünün iddışındaki tüm alanlardan okumasına izin verilir, ancak öğe oluştururken tüm alanları kullanabilir.

{
  "entities": {
    "Author": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["id"]
              }
            },
            { "action": "create" }
          ]
        }
      ]
    }
  }
}

Birlikte çalışmayı dahil edin ve hariç tutun. include bölümündeki joker karakter * tüm alanları gösterir. exclude bölümünde belirtilen alanların, include bölümünde belirtilen alanlara göre önceliği vardır. Tanım, "last_updated" alanı dışındaki tüm alanları

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ],
            // Include All Except Specific Fields
            "fields": {
              "include": [ "*" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "authenticated",
            "actions": [ "read", "update" ],
            // Explicit Include and Exclude
            "fields": {
              "include": [ "id", "title", "secret-field" ],
              "exclude": [ "secret-field" ]
            }
        },
        {
            "role": "author",
            "actions": [ "*" ],
            // Include All With No Exclusions (default)
            "fields": {
              "include": ["*"],
              "exclude": []
            }
        }
    ]
}

Politika

GEREKLI: ❌ Hayır

actionbaşına tanımlanan policy bölümü, bir istekten döndürülen sonuçları sınırlayan öğe düzeyi güvenlik kurallarını (veritabanı ilkeleri) tanımlar. database alt bölümü, istek yürütme sırasında değerlendirilen veritabanı ilkesi ifadesini belirtir.

Biçim

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<string>",
          "actions": [
            {
              "action": "<string>",
              "fields": ["<string-array>"],
              "policy": {
                "database": "<string>"
              }
            }
          ]
        }
      ]
    }
  }
}

Özellikler

	Gerekli	Tür
`database`	✔️ Evet	dizgi

Tarif

database ilkesi: sorguya çevrilen OData benzeri bir ifade, eq, ltve gtgibi işleçler de dahil olmak üzere veritabanının değerlendirmesini koşullaştırır. Bir istek için sonuçların döndürülmesi için, bir veritabanı ilkesinden çözümlenen isteğin sorgu koşulu, veritabanında yürütülürken true olarak değerlendirilmelidir.

Örnek Öğe İlkesi	Yüklem
`@item.OwnerId eq 2000`	`WHERE Table.OwnerId = 2000`
`@item.OwnerId gt 2000`	`WHERE Table.OwnerId > 2000`
`@item.OwnerId lt 2000`	`WHERE Table.OwnerId < 2000`

predicate, DOĞRU veya YANLIŞ olarak değerlendirilen bir ifadedir. Koşullar, WHERE yan tümcelerinin ve HAVING yan tümcelerinin , from yan tümcelerinin birleşim koşullarının ve Boole değerinin gerekli olduğu diğer yapıların arama koşulunda kullanılır. (Microsoft Learn Docs)

Veritabanı ilkesi

Veritabanı ilkesi ifadesi yazılırken veritabanı ilkesini yönetmek için iki tür yönerge kullanılabilir:

Yönergesi	Tarif
`@claims`	İstekte sağlanan doğrulanmış erişim belirteci içinde bir talepe erişme
`@item`	Veritabanı ilkesinin tanımlandığı varlığın alanını temsil eder

Not

Azure Static Web Apps kimlik doğrulaması (EasyAuth) yapılandırıldığında, veritabanı ilkelerinde sınırlı sayıda talep türü kullanılabilir: , , ve . Daha fazla bilgi için bkz. Azure Static Web App'in İstemci asıl verileri belgeleri.

Aşağıda birkaç örnek veritabanı ilkesi verilmişti:

@claims.UserId eq @item.OwnerId
@claims.UserId gt @item.OwnerId
@claims.UserId lt @item.OwnerId

Veri API oluşturucusu, UserId talebi değerini OwnerIdveritabanı alanının değeriyle karşılaştırır. Sonuç yükü yalnızca hem istek meta verileri hem de veritabanı ilkesi ifadesi gerçekleştiren kayıtları içerir.

Sınırlama

Veritabanı ilkeleri tablolar ve görünümler için desteklenir. Saklı yordamlar ilkelerle yapılandırılamaz.

Veritabanı ilkeleri, isteklerin veritabanında yürütülmesini engellemez. Bunun nedeni, bunların veritabanı altyapısına geçirilen oluşturulan sorgularda koşul olarak çözümlenmesidir.

Veritabanı ilkeleri yalnızca oluşturmaiçin desteklenir okuma, güncelleştirme vesilme . Saklı yordam çağrısında koşul olmadığından, bunlar eklenemez.

Desteklenen OData benzeri işleçler

Operatör	Tarif	Örnek Söz Dizimi
`and`	Mantıksal AND	`"@item.status eq 'active' and @item.age gt 18"`
`or`	Mantıksal VEYA	`"@item.region eq 'US' or @item.region eq 'EU'"`
`eq`	Eşit -tir	`"@item.type eq 'employee'"`
`gt`	Büyüktür	`"@item.salary gt 50000"`
`lt`	Küçüktür	`"@item.experience lt 5"`

Daha fazla bilgi için bkz.ikili işleçleri .

Operatör	Tarif	Örnek Söz Dizimi
`-`	Negate (sayısal)	`"@item.balance lt -100"`
`not`	Mantıksal negate (DEĞİl)	`"not @item.status eq 'inactive'"`

Daha fazla bilgi için bkz.birli işleçleri .

Varlık alanı adı kısıtlamaları

Kuralları: Bir harf veya alt çizgi (_) ile başlayıp en çok 127 harf, alt çizgi (_) veya rakamlarla (0-9) başlamalıdır.
Etki: Bu kurallara uymayan alanlar doğrudan veritabanı ilkelerinde kullanılamaz.
Çözüm: Bu adlandırma kurallarına uymayen alanlar için diğer adlar oluşturmak üzere mappings bölümünü kullanın; eşlemeleri, tüm alanların ilke ifadelerine eklenebilmesini sağlar.

Uyumsuz alanlar için `mappings` kullanma

Varlık alanı adlarınız OData söz dizimi kurallarına uymuyorsa veya bunları başka nedenlerle diğer ad olarak kullanmak istiyorsanız, yapılandırmanızın mappings bölümünde diğer adlar tanımlayabilirsiniz.

{
  "entities": {
    "<entity-name>": {
      ...
      "mappings": {
        "<field-1-name>" : "<field-1-alias>",
        "<field-2-name>" : "<field-2-alias>",
        "<field-3-name>" : "<field-3-alias>"
      }
    }
  }
}

Bu örnekte field-1-name, OData adlandırma kurallarına uymayan özgün veritabanı alanı adıdır. field-1-name ve field-1-alias eşlemesi oluşturmak, bu alana sorun olmadan veritabanı ilkesi ifadelerinde başvurulmasını sağlar. Bu yaklaşım yalnızca OData adlandırma kurallarına uymaya yardımcı olmakla kalmaz, aynı zamanda hem GraphQL hem de RESTful uç noktalarındaki veri modelinizin netliğini ve erişilebilirliğini artırır.

Örnekler

Hem talep hem de öğe yönergelerini kullanan bir Veri API'si yapılandırmasında Employee adlı bir varlığı düşünün. Veri erişiminin kullanıcı rollerine ve varlık sahipliğine göre güvenli bir şekilde yönetilmesini sağlar:

{
  "entities": {
    "Employee": {
      "source": {
        "object": "HRUNITS",
        "type": "table",
        "key-fields": ["employee NUM"],
        "parameters": {}
      },
      "mappings": {
        "employee NUM": "EmployeeId",
        "employee Name": "EmployeeName",
        "department COID": "DepartmentId"
      },
      "policy": {
        "database": "@claims.role eq 'HR' or @claims.UserId eq @item.EmployeeId"
      }
    }
  }
}

Varlık Tanımı: Employee varlığı REST ve GraphQL arabirimleri için yapılandırılır ve verileri bu uç noktalar aracılığıyla sorgulanabilir veya işlenebilir.

Kaynak Yapılandırma: Veritabanındaki HRUNITS tanımlar ve anahtar alanı olarak employee NUM.

Eşlemeleri: Diğer adlar, employee NUM, employee Nameve department COID sırasıyla EmployeeId, EmployeeNameve DepartmentIdile eşlemek için kullanılır ve alan adlarını basitleştirir ve hassas veritabanı şeması ayrıntılarını gizler.

İlke Uygulaması: policy bölümü, OData benzeri bir ifade kullanarak bir veritabanı ilkesi uygular. Bu ilke, veri erişimini İk rolüne (@claims.role eq 'HR') sahip kullanıcılarla veya UserId talebi veritabanındaki (@claims.UserId eq @item.EmployeeId) alan diğer adı EmployeeId eşleşen kullanıcılarla kısıtlar. Çalışanların İk departmanına ait olmadığı sürece yalnızca kendi kayıtlarına erişebilmelerini sağlar. İlkeler, dinamik koşullara göre satır düzeyi güvenliği zorunlu kılabilir.

Veritabanı

GEREKLI: ✔️ Evet

Bu özellik, istek yürütme sırasında değerlendirilen veritabanı ilkesi ifadesini belirtir. İlke dizesi, veritabanı tarafından önceden değerlendirilen bir sorguya çevrilen bir OData ifadesidir. Örneğin, @item.OwnerId eq 2000 ilke ifadesi WHERE <schema>.<object-name>.OwnerId = 2000sorgu koşuluna çevrilir.

Not

koşulu, TRUE, FALSEveya UNKNOWN'a kaçan bir ifadedir. Önkoşullar şu durumlarda kullanılır:

WHERE yan tümcelerinin arama koşulu
FROM yan tümcelerinin arama koşulu
FROM yan tümcelerinin birleştirme koşulları
Boole değerinin gerekli olduğu diğer yapılar.

Daha fazla bilgi için bkz.önkoşulları.

Bir istek için sonuçların döndürülmesi için, bir veritabanı ilkesinden çözümlenen isteğin sorgu koşulu, veritabanında yürütülürken true olarak değerlendirilmelidir.

Veritabanı ilkesi ifadesi yazılırken veritabanı ilkesini yönetmek için iki tür yönerge kullanılabilir:

	Tarif
`@claims`	İstekte sağlanan doğrulanmış erişim belirteci içinde bir talebe erişir
`@item`	Veritabanı ilkesinin tanımlandığı varlığın alanını temsil eder

Not

Azure Static Web Apps kimlik doğrulaması (EasyAuth) yapılandırıldığında veritabanı ilkelerinde sınırlı sayıda talep türü kullanılabilir. Bu talep türleri şunlardır: identityProvider, userId, userDetailsve userRoles. Daha fazla bilgi için bkz.Azure Static Web Apps istemci sorumlusu verilerini .

Örnekler

Örneğin, temel bir ilke ifadesi tablo içinde belirli bir alanın doğru olup olmadığını değerlendirebilir. Bu örnek, soft_delete alanının falseolup olmadığını değerlendirir.

{
  "entities": {
    "Manuscripts": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@item.soft_delete eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Önkoşullar hem claims hem de item yönerge türlerini de değerlendirebilir. Bu örnek, erişim belirtecinden UserId alanını çeker ve hedef veritabanı tablosundaki owner_id alanıyla karşılaştırır.

{
  "entities": {
    "Manuscript": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.UserId eq @item.owner_id"
              }
            }
          ]
        }
      ]
    }
  }
}

Sınırlama

Veritabanı ilkeleri tablolar ve görünümler için desteklenir. Saklı yordamlar ilkelerle yapılandırılamaz.
Veritabanı ilkeleri, bir isteğin veritabanı içinde yürütülmesini önlemek için kullanılamaz. Bu sınırlama, veritabanı ilkelerinin oluşturulan veritabanı sorgularında sorgu koşulu olarak çözümlenmesidir. Veritabanı altyapısı sonuçta bu sorguları değerlendirir.
Veritabanı ilkeleri yalnızca actionscreate, read, updateve deleteiçin desteklenir.
Veritabanı ilkesi OData ifadesinin söz dizimi yalnızca bu senaryoları destekler.
- bunlarla sınırlı olmamak üzere ikili işleçler; and, or, eq, gtve lt. Daha fazla bilgi için bkz. BinaryOperatorKind.
- - (negate) ve not işleçleri gibi tekli işleçler. Daha fazla bilgi için bkz. UnaryOperatorKind.
Veritabanı ilkelerinin alan adlarıyla ilgili kısıtlamaları da vardır.
- Bir harf veya alt çizgiyle başlayan ve en çok 127 harf, alt çizgi veya basamak içeren varlık alanı adları.
- Bu gereksinim OData belirtimlerine göredir. Daha fazla bilgi için bkz. OData Common Schema Definition Language.

Bahşiş

Belirtilen kısıtlamalara uymayan alanlara veritabanı ilkelerinde başvurulamaz. Geçici bir çözüm olarak, alanlara uygun diğer adlar atamak için varlığı eşlemeler bölümüyle yapılandırın.

GraphQL (varlıklar)

GEREKLI: ❌ Hayır

Bu kesim, bir varlığı GraphQL şemasıyla tümleştirmeyi sağlar. Geliştiricilerin GraphQL'de varlık için varsayılan değerleri belirtmesine veya değiştirmesine olanak tanır. Bu kurulum, şemanın hedeflenen yapıyı ve adlandırma kurallarını doğru şekilde yansıtmasını sağlar.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        "enabled": <true> (default) | <false>,
        "type": {
          "singular": "my-alternative-name",
          "plural": "my-alternative-name-pluralized"
        },
        "operation": "query" | "mutation" (default)
      },
    }
  }
}

{
  "entities": {
    "<string>": {
      "graphql": "<boolean>"
    }
  }
}

{
  "entities": {
    "<string>": {
      "graphql": {
        "enabled": "<boolean>",
        "type": "<string-or-object>",
        "operation": "<enum-string>"
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`enabled`	❌ Hayır	Boolean
`type`	❌ Hayır	dize veya nesne
`operation`	❌ Hayır	sabit listesi dizesi

Örnekler

Bu iki örnek işlevsel olarak eşdeğerdir.

{
  "entities": {
    "Author": {
      "graphql": true
    }
  }
}

{
  "entities": {
    "Author": {
      "graphql": {
        "enabled": true
      }
    }
  }
}

Bu örnekte, tanımlanan varlık Book, veritabanındaki kitaplarla ilgili bir veri kümesiyle ilgilendiğimizi gösterir. GraphQL segmentindeki Book varlığının yapılandırması, GraphQL şemasında nasıl temsil edilmesi ve etkileşime alınması gerektiği konusunda net bir yapı sunar.

Enabled özelliği: Book varlığı GraphQL ("enabled": true) aracılığıyla kullanılabilir hale getirilmiştir. Bu, geliştiricilerin ve kullanıcıların GraphQL işlemleri aracılığıyla kitap verilerini sorgulayıp sessize almalarını sağlar.

Type özelliği: Varlık tekil ad "Book" ve Çoğul ad "Books" GraphQL şemasında gösterilir. Bu ayrım, tek bir kitabı veya birden çok kitabı sorgularken şemanın sezgisel olarak adlandırılmış türler (tek bir giriş içinBook, bir liste için Books) sunmasını ve API'nin kullanılabilirliğini geliştirmesini sağlar.

operation özelliği: İşlem "query"olarak ayarlanır ve GraphQL aracılığıyla Book varlığıyla birincil etkileşimin verileri sessize almak (oluşturmak, güncelleştirmek veya silmek) yerine sorgulamak (almak) hedeflendiğini belirtir. Bu kurulum, kitap verilerinin değiştirildiğinden daha sık okunduğu tipik kullanım desenleriyle hizalanır.

{
  "entities": {
    "Book": {
      ...
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "Book",
          "plural": "Books"
        },
        "operation": "query"
      },
      ...
    }
  }
}

Tür (GraphQL varlığı)

GEREKLI: ❌ Hayır

Bu özellik, GraphQL şeması içindeki bir varlığın adlandırma kuralını belirler. Hem skaler dize değerlerini hem de nesne türlerini destekler. Nesne değeri tekil ve çoğul formları belirtir. Bu özellik, şemanın okunabilirliği ve kullanıcı deneyimi üzerinde ayrıntılı denetim sağlar.

Biçim

{
  "entities": {
    "<string>": {
      "graphql": {
        "type": "<string>"
      }
    }
  }
}

{
  "entities": {
    "<string>": {
      "graphql": {
        "type": {
          "singular": "<string>",
          "plural": "<string>"
        }
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`singular`	❌ Hayır	dizgi
`plural`	❌ Hayır	dizgi

Örnekler

GraphQL türü üzerinde daha da fazla denetim için tekil ve çoğul adın nasıl bağımsız olarak temsil edilir yapılandırabilirsiniz.

plural eksikse veya atlanırsa (skaler değer gibi) Veri API'si oluşturucusu, çoğullaştırma için İngilizce kuralları izleyerek adı otomatik olarak çoğullaştırmaya çalışır (örneğin: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

Özel varlık adı, dize değeriyle type parametresi kullanılarak belirtilebilir. Bu örnekte altyapı, çoğullaştırma için yaygın İngilizce kurallarını kullanarak bu adın tekil ve çoğul varyantları arasında otomatik olarak ayrımlar oluşturur.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": "bookauthor"
      }
    }
  }
}

Adları açıkça belirtmeyi seçerseniz, type.singular ve type.plural özelliklerini kullanın. Bu örnek her iki adı da açıkça ayarlar.

{
  "entities": {
    "Author": {
      "graphql": {
        "type": {
          "singular": "bookauthor",
          "plural": "bookauthors"
        }
      }
    }
  }
}

her iki örnek de işlevsel olarak eşdeğerdir. her ikisi de bookauthors varlık adını kullanan bir GraphQL sorgusu için aynı JSON çıkışını döndürür.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

{
  "data": {
    "bookauthors": {
      "items": [
        {
          "first_name": "Henry",
          "last_name": "Ross"
        },
        {
          "first_name": "Jacob",
          "last_name": "Hancock"
        },
        ...
      ]
    }
  }
}

İşlem (GraphQL varlığı)

GEREKLI: ❌ Hayır

Saklı yordamlara eşlenen varlıklar için operation özelliği saklı yordamın erişilebilir olduğu GraphQL işlem türünü (sorgu veya mutasyon) tanımlar. Bu ayar, işlevselliği etkilemeden şemanın mantıksal olarak düzenlenmesine ve GraphQL en iyi yöntemlerine bağlı kalınmasına olanak tanır.

Not

{entity}.type özellik değeri stored-procedureolarak ayarlanarak bir varlık saklı yordam olarak belirtilir. Saklı yordam söz konusu olduğunda, yeni bir GraphQL türü executeXXX otomatik olarak oluşturulur. Ancak operation özelliği, geliştiricinin bu türün konumunu şemanın mutation veya query bölümlerine zorlamasına olanak tanır. Bu özellik şema hegenesine izin verir ve operation değerden bağımsız olarak işlevsel bir etki yoktur.

Eksikse, varsayılan operationmutationolur.

Biçim

{
  "entities": {
    "<string>": {
      "graphql": {
        "operation": "<string-enum>"
      }
    }
  }
}

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tarif
`query`	Temel alınan saklı yordam sorgu olarak kullanıma sunulur
`mutation`	Temel alınan saklı yordam bir mutasyon olarak ortaya çıkar

Örnekler

operation mutationolduğunda GraphQL şeması şuna benzer olacaktır:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

operation queryolduğunda GraphQL şeması şuna benzer olacaktır:

GraphQL şeması şuna benzer olacaktır:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Not

operation özelliği yalnızca işlemin GraphQL şemasına yerleştirilmesiyle ilgili, işlemin davranışını değiştirmez.

Etkin (GraphQL varlığı)

GEREKLI: ❌ Hayır

GraphQL uç noktasını etkinleştirir veya devre dışı bırakır. Bir varlığın GraphQL uç noktaları aracılığıyla kullanılabilir olup olmadığını denetler. enabled özelliğinin geçişini yapmak, geliştiricilerin GraphQL şemasındaki varlıkları seçmeli olarak kullanıma sunmalarına olanak tanır.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "graphql": {
        ...
        "enabled": true | false
      }
    }
  }
}

REST (varlıklar)

GEREKLI: ❌ Hayır

Yapılandırma dosyasının rest bölümü, her veritabanı varlığı için RESTful uç noktalarına ince ayar yapmaya ayrılmıştır. Bu özelleştirme özelliği, kullanıma sunulan REST API'nin belirli gereksinimlerle eşleşmesini sağlayarak hem yardımcı programı hem de tümleştirme özelliklerini geliştirir. Varsayılan çıkarılmış ayarlar ve istenen uç nokta davranışları arasındaki olası uyuşmazlıkları giderir.

Biçim

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": "/entity-path", (default <entity-name>)
        "methods": ["GET", "POST" (default)]
      },
      ...
    }
  }
}

Özellikler

	Gerekli	Tür
`enabled`	✔️ Evet	Boolean
`path`	❌ Hayır	dizgi
`methods`	❌ Hayır	dize dizisi

Örnekler

Bu iki örnek işlevsel olarak eşdeğerdir.

{
  "entities": {
    "Author": {
      "source": {
        "object": "dbo.authors",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ],
      "rest": true
    }
  }
}

{
  "entities": {
    "Author": {
      ...
      "rest": {
        "enabled": true
      }
    }
  }
}

Bir varlık için REST yapılandırmasının başka bir örneği aşağıda verilmiştir.

{
  "entities" {
    "User": {
      "rest": {
        "enabled": true,
        "path": "/User"
      },
      ...
    }
  }
}

Etkin (REST varlığı)

GEREKLI: ❌ Hayır

Bu özellik, REST API içindeki varlıkların görünürlüğü için bir iki durumlu düğme işlevi görür. geliştiriciler, enabled özelliğini true veya falseolarak ayarlayarak belirli varlıklara erişimi denetleyerek uygulama güvenliği ve işlevsellik gereksinimleriyle uyumlu uyarlanmış bir API yüzeyi sağlar.

Atlanırsa veya eksikse, varsayılan enabled değeri trueolur.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "rest": {
        "enabled": <true> (default) | <false>
      }
    }
  }
}

Yol (REST varlığı)

GEREKLI: ❌ Hayır

path özelliği, REST API aracılığıyla bir varlığa erişmek için kullanılan URI kesimini belirtir. Bu özelleştirme, varsayılan varlık adının ötesinde daha açıklayıcı veya basitleştirilmiş uç nokta yolları sağlayarak API'de gezinilebilirliği ve istemci tarafı tümleştirmesini geliştirir. Varsayılan olarak, yol /<entity-name>.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "rest": {
        ...
        "path": "/entity-path"
      }
    }
  }
}

Örnekler

Bu örnek, /auth uç noktasını kullanarak Author varlığını kullanıma sunar.

{
  "entities": {
    "Author": {
      "rest": {
        "path": "/auth"
      }
    }
  }
}

Yöntemler (REST varlığı)

GEREKLI: ❌ Hayır

Saklı yordamlara özel olarak geçerli olan methods özelliği, yordamın yanıt verebileceği HTTP fiillerini (örneğin, GET, POST) tanımlar. Yöntemler, RESTful standartları ve istemci beklentileriyle uyumluluğu sağlayarak REST API aracılığıyla saklı yordamların nasıl kullanıma sunulduğu üzerinde hassas denetim sağlar. Bu bölümde, platformun esneklik ve geliştirici denetimine olan taahhüdü altı çizilir ve her uygulamanın özel ihtiyaçlarına göre uyarlanmış hassas ve sezgisel API tasarımı sağlanır.

Atlanırsa veya eksikse, varsayılan methodsPOSTolur.

Biçim

{
  "entities" {
    "<entity-name>": {
      ...
      "rest": {
        ...
        "methods": [ "GET" (default), "POST" ]
      }
    }
  }
}

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tarif
`get`	HTTP GET isteklerini kullanıma sunar
`post`	HTTP POST isteklerini kullanıma sunar

Örnekler

Bu örnek, altyapıya stp_get_bestselling_authors saklı yordamının yalnızca HTTP GET eylemleri desteklediğini açıklar.

{
  "entities": {
    "BestSellingAuthor": {
      "source": {
        "object": "dbo.stp_get_bestselling_authors",
        "type": "stored-procedure",
        "parameters": {
          "depth": 10
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

Eşlemeler (varlıklar)

GEREKLI: ❌ Hayır

mappings bölümü veritabanı nesnesi alanları için diğer adların veya kullanıma sunulan adların yapılandırılmasını sağlar. Yapılandırılmış kullanıma sunulan adlar hem GraphQL hem de REST uç noktaları için geçerlidir.

Önemli

GraphQL'in etkinleştirildiği varlıklar için, yapılandırılmış kullanıma sunulan adın GraphQL adlandırma gereksinimlerini karşılaması gerekir. Daha fazla bilgi için bkz. GraphQL adları belirtimi.

Biçim

{
  ...
  "entities" {
    "<entity-name>": {
      "rest":{ ... },
      "graphql": { ... },
      "source": { ... },
      "mappings": {
        "<field-1-name>" : "<field-1-alias>",
        "<field-2-name>" : "<field-2-alias>",
        "<field-3-name>" : "<field-3-alias>"
      }
    }
  }
}

Örnekler

Bu örnekte, veritabanı nesnesi dbo.magazinessku_title alanı titleadı kullanılarak kullanıma sunulur. Benzer şekilde, sku_status alanı hem REST hem de GraphQL uç noktalarına status olarak sunulur.

{
  "entities": {
    "Magazine": {
      ...
      "mappings": {
        "sku_title": "title",
        "sku_status": "status"
      }
    }
  }
}

Aşağıda başka bir eşleme örneği verilmiştir.

{
  "entities": {
    "Book": {
      ...
      "mappings": {
        "id": "BookID",
        "title": "BookTitle",
        "author": "AuthorName"
      }
    }
  }
}

Eşlemeleri: mappings nesnesi, veritabanı alanlarını (BookID, BookTitle, AuthorName) harici olarak kullanılan daha sezgisel veya standartlaştırılmış adlara (id, title, author) bağlar. Bu diğer ad çeşitli amaçlara hizmet eder:

Netlik ve Tutarlılık: Temel alınan veritabanı şemasından bağımsız olarak API genelinde net ve tutarlı adlandırmanın kullanılmasına olanak tanır. Örneğin, veritabanındaki BookID API'de id olarak temsil edilir ve bu da uç noktayla etkileşim kuran geliştiriciler için daha sezgiseldir.
GraphQL Uyumluluğu: Diğer ad alan adlarına yönelik bir mekanizma sağlayarak, GraphQL arabirimi aracılığıyla kullanıma sunulan adların GraphQL adlandırma gereksinimlerine uygun olmasını sağlar. GraphQL'in adlarla ilgili katı kuralları olduğundan adlara dikkat etmek önemlidir (örneğin boşluk olmaması, harf veya alt çizgiyle başlaması vb.). Örneğin, bir veritabanı alanı adı bu ölçütleri karşılamıyorsa, eşlemeler aracılığıyla uyumlu bir ada diğer ad eklenebilir.
Esneklik: Bu diğer ad, veritabanı şeması ile API arasında bir soyutlama katmanı ekler ve diğerinde değişiklik gerektirmeden birinde değişiklik yapılmasını sağlar. Örneğin, veritabanındaki alan adı değişikliği, eşleme tutarlı kalırsa API belgelerinde veya istemci tarafı kodunda güncelleştirme gerektirmez.
Alan Adını Gizleme: Eşleme, alan adlarının gizlenmesini sağlar ve bu da yetkisiz kullanıcıların veritabanı şeması veya depolanan verilerin doğası hakkında hassas bilgiler çıkarmasını önlemeye yardımcı olabilir.
Özel Bilgileri Koruma: Alanları yeniden adlandırarak, veritabanının özgün alan adları aracılığıyla ima edilebilecek özel adları veya iş mantığını da koruyabilirsiniz.

İlişkiler (varlıklar)

GEREKLI: ❌ Hayır

Bu bölüm eşlemeleri, varlıkların kullanıma sunulan diğer varlıklarla nasıl ilişkili olduğunu eşleyen bir ilişki tanımları kümesi içerir. Bu ilişki tanımları isteğe bağlı olarak ilişkileri desteklemek ve zorlamak için kullanılan temel veritabanı nesneleriyle ilgili ayrıntıları da içerebilir. Bu bölümde tanımlanan nesneler, ilgili varlıkta GraphQL alanları olarak sunulur. Daha fazla bilgi için bkz. Veri API'si oluşturucu ilişkileri dökümü.

Not

İlişkiler yalnızca GraphQL sorguları ile ilgilidir. REST uç noktaları aynı anda yalnızca bir varlığa erişir ve iç içe türleri döndüremez.

relationships bölümünde, varlıkların Veri API'sini oluşturucusu içinde nasıl etkileşim kurabilecekleri açıklanır ve bu ilişkiler için ilişkilendirmeler ve olası veritabanı desteği ayrıntılı olarak açıklanır. Her ilişkinin relationship-name özelliği hem gereklidir hem de belirli bir varlık için tüm ilişkilerde benzersiz olmalıdır. Özel adlar net, tanımlanabilir bağlantılar sağlar ve bu yapılandırmalardan oluşturulan GraphQL şemasının bütünlüğünü korur.

İlişki	Önem düzeyi	Örnek
bire çok	`many`	Bir kategori varlığı birçok yapılacaklar varlığıyla ilişkilendirilebilir
çoka bir	`one`	Birçok yapılacaklar varlığı bir kategori varlığıyla ilişkilendirilebilir
çoka çok	`many`	Bir yapılacaklar varlığı birçok kullanıcı varlığıyla ve bir kullanıcı varlığı da birçok yapılacaklar varlığıyla ilişkilendirilebilir

Biçim

{{
  "entities": {
    "entity-name": {
      ...
      "relationships": {
        "relationship-name": {
          "cardinality": "one" | "many",
          "target.entity": "target-entity-name",
          "source.fields": ["source-field-name"],
          "target.fields": ["target-field-name"],
          "linking.object": "linking-object-name",
          "linking.source.fields": ["linking-source-field-name"],
          "linking.target.fields": ["linking-target-field-name"]
        }
      }
    }
  }
}

Özellikler

	Gerekli	Tür
`cardinality`	✔️ Evet	sabit listesi dizesi
`target.entity`	✔️ Evet	dizgi
`source.fields`	❌ Hayır	dize dizisi
`target.fields`	❌ Hayır	dize dizisi
`linking.<object-or-entity>`	❌ Hayır	dizgi
`linking.source.fields`	❌ Hayır	dize dizisi
`linking.target.fields`	❌ Hayır	dize dizisi

Örnekler

İlişkileri göz önünde bulundurarak, bire çok, çoka birve çoka çok ilişkileri arasındaki farkları karşılaştırmak en iyisidir.

Bire çok

İlk olarak, kullanıma sunulan Category varlığıyla Book varlığıyla bire çok ilişkisine sahip bir ilişki örneğini ele alalım. Burada kardinalite manyolarak ayarlanır. Her Book varlığı yalnızca tek bir Category varlığıyla ilişkilendirilirken, her Category birden çok ilişkili Book varlığı olabilir.

{
  "entities": {
    "Book": {
      ...
    },
    "Category": {
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Bu örnekte, source.fields listesi kaynak varlığın (Category) id alanını belirtir. Bu alan, target varlığındaki ilgili öğeye bağlanmak için kullanılır. Buna karşılık, target.fields listesi hedef varlığın (Book) category_id alanını belirtir. Bu alan, source varlığındaki ilgili öğeye bağlanmak için kullanılır.

Bu ilişki tanımlandığında, ortaya çıkan GraphQL şeması bu örneğe benzemelidir.

type Category
{
  id: Int!
  ...
  books: [BookConnection]!
}

Çoka bir

Ardından, kardinaliteyi olarak ayarlayan çoka bir göz önünde bulundurun. Kullanıma sunulan Book varlığıyla ilgili tek bir Category varlığı olabilir. Category varlığıyla ilgili birden çok Book varlığı olabilir.

{
  "entities": {
    "Book": {
      "relationships": {
        "books_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      },
      "Category": {
        ...
      }
    }
  }
}

Burada, source.fields listesi kaynak varlığın (Book) category_id alanının ilgili hedef varlığın (Category) id alanına başvurduğunu belirtir. Tersine, target.fields listesi ters ilişkiyi belirtir. Bu ilişkiyle, sonuçta elde edilen GraphQL şeması artık Kitaplar'dan Kategorilere bir eşleme içeriyor.

type Book
{
  id: Int!
  ...
  category: Category
}

Çoka çok

Son olarak, çoka çok ilişkisi, many kardinalitesi ve arka veritabanında ilişki oluşturmak için hangi veritabanı nesnelerinin kullanıldığını tanımlamak için daha fazla meta veriyle tanımlanır. Burada, Book varlığı birden çok Author varlığa ve diğer taraftan Author varlığı birden çok Book varlığına sahip olabilir.

{
  "entities": {
    "Book": {
      "relationships": {
        ...,
        "books_authors": {
          "cardinality": "many",
          "target.entity": "Author",
          "source.fields": [ "id" ],
          "target.fields": [ "id" ],
          "linking.object": "dbo.books_authors",
          "linking.source.fields": [ "book_id" ],
          "linking.target.fields": [ "author_id" ]
        }
      },
      "Category": {
        ...
      },
      "Author": {
        ...
      }
    }
  }
}

Bu örnekte, source.fields ve target.fields her ikisi de ilişki tablosunun hem kaynak (Book) hem de hedef (Author) varlıklarının birincil tanımlayıcısını (id) kullandığını gösterir. linking.object alanı, ilişkinin dbo.books_authors veritabanı nesnesinde tanımlandığını belirtir. Ayrıca, linking.source.fields bağlama nesnesinin book_id alanının Book varlığının id alanına başvurduğunu belirtir ve linking.target.fields bağlama nesnesinin author_id alanının Author varlığının id alanına başvurduğunu belirtir.

Bu örnek, bu örneğe benzer bir GraphQL şeması kullanılarak açıklanabilir.

type Book
{
  id: Int!
  ...
  authors: [AuthorConnection]!
}

type Author
{
  id: Int!
  ...
  books: [BookConnection]!
}

Önem düzeyi

GEREKLI: ✔️ Evet

Geçerli kaynak varlığın yalnızca hedef varlığın tek bir örneğiyle mi yoksa birden çok ile mi ilişkili olduğunu belirtir.

Değer

Bu özellik için izin verilen değerlerin listesi aşağıdadır:

	Tarif
`one`	Kaynak, hedeften yalnızca bir kayıtla ilişkilidir
`many`	Kaynak, hedeften sıfırdan çoka kayıtla ilişkilendirilebilir

Hedef varlık

GEREKLI: ✔️ Evet

Yapılandırmada ilişkinin hedefi olan başka bir yerde tanımlanan varlığın adı.

Kaynak alanlar

GEREKLI: ❌ Hayır

Hedef varlıktaki ilgili öğeye bağlanmak için kullanılan kaynak varlığında eşleme için kullanılan alanı tanımlamak için isteğe bağlı bir parametre.

Bahşiş

İlişkiyi otomatik olarak çıkarsamak için kullanılabilecek iki veritabanı nesnesi arasında veritabanında yabancı anahtar kısıtlaması varsa bu alan gerekli değildir.

Hedef alanlar

GEREKLI: ❌ Hayır

Kaynak varlıktaki ilgili öğeye bağlanmak için kullanılan hedef varlığında eşleme için kullanılan alanı tanımlamak için isteğe bağlı bir parametre.

Bahşiş

İlişkiyi otomatik olarak çıkarsamak için kullanılabilecek iki veritabanı nesnesi arasında veritabanında yabancı anahtar kısıtlaması varsa bu alan gerekli değildir.

Nesne veya varlık bağlama

GEREKLI: ❌ Hayır

Çoka çok ilişkiler için, diğer iki varlık arasında ilişki tanımlamak için gereken verileri içeren veritabanı nesnesinin veya varlığının adı.

Kaynak alanları bağlama

GEREKLI: ❌ Hayır

Kaynak varlıkla ilişkili veritabanı nesnesinin veya varlık alanının adı.

Hedef alanları bağlama

GEREKLI: ❌ Hayır

Hedef varlıkla ilişkili veritabanı nesnesinin veya varlık alanının adı.

Önbellek (varlıklar)

GEREKLI: ❌ Hayır

Varlık için önbelleğe almayı etkinleştirir ve yapılandırr.

Biçim

{
  "entities": {
    "<string>": {
      "cache": {
        "enabled": <true> | <false> (default),
        "ttl-seconds": (integer, default: 5)
      }
    }
  }
}

Özellikler

	Gerekli	Tür	Temerrüt
`enabled`	❌ Hayır	Boolean	`false`
`ttl-seconds`	❌ Hayır	tam sayı	`5`

Örnekler

Bu örnekte önbellek etkinleştirilir ve öğelerin süresi 30 saniye sonra dolar.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 30
      }
    }
  }
}

Etkin (Önbellek varlığı)

GEREKLI: ❌ Hayır

Varlık için önbelleğe almayı etkinleştirir. Genel ayar trueolsa bile varsayılan olarak false olur.

Veritabanı Nesnesi Desteği

Nesne türü	Önbellek desteği
Masa	✅ Evet
Görünüm	✅ Evet
Saklı Yordam	✖️ Hayır
Konteyner	✖️ Hayır

HTTP Üst Bilgi Desteği

İstek Üst Bilgisi	Önbellek desteği
`no-cache`	✖️ Hayır
`no-store`	✖️ Hayır
`max-age`	✖️ Hayır
`public`	✖️ Hayır
`private`	✖️ Hayır
`etag`	✖️ Hayır

Biçim

{
  "entities": {
    "<string>": {
      "cache": {
        "enabled": "<boolean>"
      }
    }
  }
}

Örnekler

Bu örnekte önbellek devre dışıdır.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": false
      }
    }
  }
}

Saniye olarak TTL (Önbellek varlığı)

GEREKLI: ❌ Hayır

Biçim

{
  "entities": {
    "<string>": {
      "cache": {
        "ttl-seconds": <integer (inherited)>
      }
    }
  }
}

Örnekler

Bu örnekte önbellek etkinleştirilir ve öğelerin süresi 15 saniye sonra dolar. Atlandığında, bu ayar genel ayarı veya varsayılanı devralır.

{
  "entities": {
    "Author": {
      "cache": {
        "enabled": true,
        "ttl-seconds": 15
      }
    }
  }
}

Aracılığıyla paylaş

Veri API'si oluşturucu yapılandırma şeması başvurusu

Söz dizimine genel bakış

Üst düzey özellikler

Örnek yapılandırma

Ortam

Yapılandırma özellikleri

Şema

Biçim

Örnekler

Veri kaynağı

Biçim

Özellikler

Veritabanı türü

Biçim

Değer

Bağlantı dizesi

Biçim

Bağlantı dayanıklılığı

Azure SQL ve SQL Server

Örnekler

Seçenekler

Biçim

Örnekler

Veri kaynağı dosyaları

Biçim

Yapılandırma dosyasıyla ilgili dikkat edilmesi gerekenler

Bilinen sorunlar

Örnekler

Çalışma zamanı

Biçim

Özellikler

Örnekler

GraphQL (çalışma zamanı)

Biçim

Özellikler

Etkin (GraphQL çalışma zamanı)

Biçim

Örnekler

Yol (GraphQL çalışma zamanı)

Biçim

Örnekler

İçe aktarmaya izin ver (GraphQL çalışma zamanı)

Biçim

Örnekler

Birden çok mutasyon (GraphQL çalışma zamanı)

Biçim

Özellikler

Birden çok mutasyon - oluşturma (GraphQL çalışma zamanı)

Biçim

Özellikler

Örnekler

REST (çalışma zamanı)

Biçim

Özellikler

Etkin (REST çalışma zamanı)

Biçim

Örnekler

Yol (REST çalışma zamanı)

Biçim

Örnekler

İstek gövdesi katı (REST çalışma zamanı)

Biçim

Örnekler

Konak (çalışma zamanı)

Biçim

Özellikler

Örnekler

Mod (Konak çalışma zamanı)

Biçim

Değer

CORS (Konak çalışma zamanı)

Biçim

Özellikler

Kimlik bilgilerine izin ver (Konak çalışma zamanı)

Biçim

Origins (Konak çalışma zamanı)

Biçim

Örnekler

Kimlik doğrulaması (Konak çalışma zamanı)