NoSQL için Azure Cosmos DB için Veri API oluşturucusu'nu ayarlama

NoSQL için Azure Cosmos DB, şemadan bağımsız bir belge veritabanıdır. İlişkisel veritabanlarının aksine Azure Cosmos DB, Data API Builder'ın (DAB) otomatik olarak içeri aktarabileceği önceden tanımlanmış bir şemaya sahip değildir. Bu kılavuzda GraphQL şema dosyası oluşturma ve DAB'yi Azure Cosmos DB kapsayıcılarınızla çalışacak şekilde yapılandırma işlemleri açıklanmaktadır.

Önkoşullar

En az bir veritabanı ve kapsayıcısı olan NoSQL hesabı için Azure Cosmos DB
Veri API'si oluşturucu CLI. CLI'yi yükleme

Şema gereksinimini anlama

NoSQL için Azure Cosmos DB bir şemayı zorlamadığından, DAB verilerinizden otomatik olarak GraphQL türleri oluşturamaz. Bunun yerine şunları tanımlayan bir GraphQL şema dosyası sağlamanız gerekir:

Kapsayıcınızın belge yapısını temsil eden nesne türleri
@model GraphQL türlerini DAB yapılandırmanızdaki varlık adlarına eşleyen yönerge
Alan @authorize düzeyinde erişimi belirli rollere kısıtlayan yönerge (isteğe bağlı)

Aşağıdaki örnekleri kullanarak şemayı el ile oluşturabilir veya komutuyla dab export mevcut Cosmos DB verilerinden oluşturabilirsiniz.

GraphQL şema dosyası oluşturma

Veri modelinizi açıklayan bir .gql dosya oluşturun. Şema dosyası, DAB için özel yönergeler içeren standart GraphQL Şema Tanım Dili 'ni (SDL) kullanır.

Temel şema örneği

Bu örnek, Book kitap kapsayıcısında bulunan ortak alanlara sahip bir tür tanımlar:

type Book @model(name: "Book") {
  id: ID
  title: String
  year: Int
  pages: Int
  Authors: [Author]
}

type Author @model(name: "Author") {
  id: ID
  firstName: String
  lastName: String
}

Cosmos DB verilerinden şema oluşturma

Kapsayıcılarınızda zaten veri varsa, başlangıç şeması oluşturmak için örnekleyebilirsiniz. Bu komut, ile -obelirttiğiniz çıkış dizinine çıkarımlı bir GraphQL şema dosyası yazar.

Bash
Komut İstemi

dab export \
  --graphql \
  --generate \
  -o ./schema-out

dab export ^
  --graphql ^
  --generate ^
  -o .\schema-out

Varsayılan olarak, örnekleme TopNExtractor kullanır.

Desteklenen örnekleme modları , TopNExtractorve EligibleDataSamplerşeklindedirTimePartitionedSampler.

Uyarı

-o / --output parametresi gereklidir. Bir şema dosyası adı belirtmezseniz, DAB çıkış dizininde schema.gql öğesini oluşturur.

Diğer modlar ve seçenekler için dab export CLI referansına bakın.

@model yönergesi gereklidir. GraphQL türünü DAB yapılandırma dosyanızdaki bir varlık adıyla eşler. parametresi varlık name adıyla tam olarak eşleşmelidir.

Uyarı

Authors: [Author] alanı, ayrı bir kapsayıcıyla bir ilişki değil, Kitap belgesinde gömülü bir diziyi temsil eder. NoSQL için Azure Cosmos DB'de, ilgili veriler ayrı kapsayıcılarda depolanmak yerine aynı belgeye eklenmelidir.

Yetkilendirme içeren şema

Belirli alanlara erişimi kısıtlamak için yönergesini @authorize kullanın. Bu yönerge, alana hangi rollerin erişebileceğini belirten bir roles parametre kabul eder.

type Book @model(name: "Book") {
  id: ID
  title: String @authorize(roles: ["authenticated", "metadataviewer"])
  internalNotes: String @authorize(roles: ["editor"])
  Authors: [Author]
}

Bu örnekte:

Sadece title veya authenticated rolüne sahip kullanıcılar metadataviewer alanına erişebilir.
internalNotes alanına yalnızca editor rolüne sahip kullanıcılar erişebilir
@authorize olmadan var olan alanlara, varlık düzeyi izinlerine göre erişilebilir.

Ayrıca türün tamamına erişimi kısıtlamak için tür düzeyinde de uygulayabilirsiniz @authorize :

type InternalReport @model(name: "InternalReport") @authorize(roles: ["editor", "auditor"]) {
  id: ID
  title: String
  confidentialData: String
}

Önemli

yönergesi, @authorize çalışma zamanı yapılandırmasında tanımlanan varlık düzeyi izinlerine ek olarak çalışır. Hem @authorize yönergesi hem de varlık izinleri, bir isteğin başarılı olması için erişime izin vermelidir.

Örneğin, bir alanda @authorize(roles: ["editor"])varsa ancak varlığın rol için editor izin girişi yoksa, bu alana erişim reddedilir.

Uyarı

@authorize(policy: "...") bu şema akışında desteklenmez. @authorize(roles: [...]) adresini kullanın.

DAB çalışma zamanını yapılandırma

Şema dosyanızı oluşturduktan sonra DAB'yi Azure Cosmos DB hesabınızla kullanacak şekilde yapılandırın.

Yapılandırmayı başlatma

dab init komutunu kullanarak Azure Cosmos DB için bir yapılandırma dosyası oluşturun:

Bash
Komut İstemi

dab init \
  --database-type cosmosdb_nosql \
  --cosmosdb_nosql-database <your-database-name> \
  --graphql-schema schema.gql \
  --connection-string "<your-connection-string>"

dab init ^
  --database-type cosmosdb_nosql ^
  --cosmosdb_nosql-database <your-database-name> ^
  --graphql-schema schema.gql ^
  --connection-string "<your-connection-string>"

<your-database-name> ile Azure Cosmos DB veritabanı adınızı ve <your-connection-string> ile bağlantı dizenizi değiştirin.

İsteğe bağlı olarak, veri kaynağı yapılandırmasında varsayılan bir kapsayıcı ayarlamak için ekleyin --cosmosdb_nosql-container <your-container-name> .

Tavsiye

Üretim ortamları için, bunları sabit kodlamak yerine bağlantı dizeleri için ortam değişkenlerini kullanın:

dab init \
    --database-type cosmosdb_nosql \
    --cosmosdb_nosql-database <your-database-name> \
    --graphql-schema schema.gql \
    --connection-string "@env('COSMOSDB_CONNECTION_STRING')"

Varlık ekleme

Kapsayıcılarınızla uyumlu varlıklar ekleyin. Varlık adı şemanızdaki değerle @model(name: "...") eşleşmelidir:

Bash
Komut İstemi

dab add Book \
  --source Book \
  --permissions "anonymous:read"

dab add Book ^
  --source Book ^
  --permissions "anonymous:read"

--source parametresi ya <container-name> ya da <database-name>.<container-name> kabul eder. Hem veritabanı hem de kapsayıcı hakkında açık olmak istediğinizde iki bölümlü biçimi kullanın.

Yapılandırma dosyası örneği

Başlatma işleminden sonra yapılandırma dosyanız aşağıdaki örneğe benzer görünmelidir:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/download/v1.2.11/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "options": {
      "database": "Library",
      "schema": "schema.gql"
    },
    "connection-string": "@env('COSMOSDB_CONNECTION_STRING')"
  },
  "entities": {
    "Book": {
      "source": "Book",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "metadataviewer",
          "actions": ["read"]
        }
      ]
    }
  }
}

Uyarı

schema Yapılandırma dosyasındaki yol, DAB yapılandırma dosyasının konumuna göredir. GraphQL şema dosyanızın doğru dizinde olduğundan emin olun.

Bu $schema URL belirli bir DAB sürümünü gösterir. DAB sürümünüzle eşleşen şema URL'sini kullanın.

Rol tabanlı alan erişimi

@authorizeyönergesini rollerle kullandığınızda, rollerin nasıl atandığını göz önünde bulundurun.

Scenario	Rol ataması	`@authorize` alanlarına erişim
Anonim istek	Atanmış rol yok	Reddedildi
Kimliği doğrulanmış istek	Sistem `authenticated` rolü otomatik olarak atanır	Rol eşleşiyorsa izin verilir
Özel rol isteği	`X-MS-API-ROLE` Başlığı rol ismiyle birlikte ekleyin	Rol eşleşiyorsa izin verilir

Bu tablo, açıkça içeren @authorizealanlar veya türler için geçerlidir. olmayan @authorizealanlar için varlık düzeyi izinleri erişimi belirler.

Kimliği doğrulanmış isteklere özel bir rol gerektiğinde, X-MS-API-ROLE başlığını gönderin:

GET /graphql HTTP/1.1
Host: localhost:5000
Authorization: Bearer <your-jwt-token>
X-MS-API-ROLE: metadataviewer

Kapsayıcılar arası sorgular

Kapsayıcılar arasında GraphQL işlemleri, NoSQL üzerinde Azure Cosmos DB tarafından desteklenmez.

veya dab addkullanarak dab update farklı kapsayıcılardaki varlıklar arasındaki ilişkileri yapılandırmaya çalışırsanız, CLI doğrulaması başarısız olur.

CLI hata iletisi: Adding/updating Relationships is currently not supported in CosmosDB.

İlişki yapılandırma ayrıntıları (diğer veritabanları için desteklenir) için bkz. İlişkiler yapılandırması.

Kapsayıcılar arası sınırlamalara geçici çözüm

Bu sınırlamayı geçici olarak çözmek için veri modelinizi tek bir kapsayıcı içinde eklenmiş belgeleri kullanacak şekilde yeniden yapılandırmayı göz önünde bulundurun. Bu yaklaşım genellikle Azure Cosmos DB için daha verimlidir ve NoSQL veri modelleme en iyi yöntemleriyle uyumlu hale getirilir.

Örneğin, ilişkileri olan ayrı Book ve Author kapsayıcılar yerine:

// Embedded model in a single container
{
  "id": "book-1",
  "title": "Introduction to DAB",
  "authors": [
    {
      "firstName": "Jane",
      "lastName": "Developer"
    }
  ]
}

Veri modelleme stratejileri hakkında daha fazla bilgi için bkz. Azure Cosmos DB'de veri modelleme.

REST API kullanılabilirliği

Veri API'leri oluşturucusu, NoSQL için Azure Cosmos DB için REST uç noktaları oluşturmaz çünkü Azure Cosmos DB belge işlemleri için kapsamlı bir yerel REST API sağlar.

NOSQL için Azure Cosmos DB ile DAB kullandığınızda, DAB yalnızca GraphQL uç noktalarını kullanıma sunar ve OpenAPI oluşturmaz. REST aracılığıyla verilerinize erişmek için Azure Cosmos DB REST API'sini doğrudan kullanın.

Yaygın yapılandırma sorunları

Şema dosyası bulunamadı

Hata: GraphQL schema file not found
Çözüm: Yapılandırmanızdaki yolun yapılandırma dosyası konumuna göre ayarlandığından emin olun schema .

Varlık adı uyuşmazlığı

Hata: Entity '<name>' not found in schema
Çözüm: Yapılandırmanızdaki varlık adının yönergeyle tam olarak eşleştiklerini @model(name: "...") doğrulayın. Adlar büyük/küçük harfe duyarlıdır.

Yetkisiz alan erişimi

Hata: GraphQL yetkilendirme hatası (örneğin, role izin verilmediğinde)
Çözüm: Hem rollerin hem de @authorize varlık izinlerinin istekte bulunan rol için erişime izin verdiğinden denetleyin.

Sonraki adım

Hızlı Başlangıç: NoSQL ile Veri API Oluşturucusunu Kullanma

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-04-01

NoSQL için Azure Cosmos DB için Veri API oluşturucusu'nu ayarlama

Önkoşullar

Şema gereksinimini anlama

GraphQL şema dosyası oluşturma

Temel şema örneği

Cosmos DB verilerinden şema oluşturma

Yetkilendirme içeren şema

DAB çalışma zamanını yapılandırma

Yapılandırmayı başlatma

Varlık ekleme

Yapılandırma dosyası örneği

Rol tabanlı alan erişimi

Kapsayıcılar arası sorgular

Kapsayıcılar arası sınırlamalara geçici çözüm

REST API kullanılabilirliği

Yaygın yapılandırma sorunları

Sonraki adım

İlgili içerik

Geri Bildirim

Ek kaynaklar