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

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:

Örnek yapılandırmalar

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": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

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:

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.

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

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.

Veri kaynağı

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": <string>,
    "connection-string": <string>,
    
    // mssql-only
    "options": {
      "set-session-context": <true> (default) | <false>
    },
    
    // cosmosdb_nosql-only
    "options": {
      "database": <string>,
      "container": <string>,
      "schema": <string>
    }
  }
}

Özellikler

Veritabanı türü

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

Biçim

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

Tür değerleri

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

Bağlantı dizesi

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 isteklerden sonraki yeniden deneme süresi bu formül kullanılarak hesaplanır (geçerli yeniden deneme girişiminin rolduğu varsayılır): $r^2$

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

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, Azure'da Barındırıldığında Yönetilen Hizmet Kimliklerini (MSI) kullanarak hedef veritabanına da bağlanabilir. DefaultAzureCredential kitaplığında tanımlanan Azure.Identity, 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.

• Kullanıcı Tarafından Atanan Yönetilen Kimlik (UMI): Kullanıcı Tarafından Atanan Yönetilen Kimliğin istemci kimliğiniz: yerine Kimlik Doğrulaması ve Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>; özelliklerini bağlantı dizenize ekleyin.
• Sistem Tarafından Atanan Yönetilen Kimlik (SMI): Kimlik Doğrulaması özelliğini ekleyin ve UserId ve Parola bağımsız değişkenlerini bağlantı dizenizden dışlar: Authentication=Active Directory Managed Identity;. UserId ve Password bağlantı dizesi özelliklerinin olmaması, SISTEM tarafından atanan yönetilen kimliği kullanarak kimlik doğrulaması için DAB'ye işaret eder.

Azure SQL veya SQL Server ile Yönetilen Hizmet Kimliği yapılandırma hakkında daha fazla bilgi için bkz. Azure SQLiçin Microsoft Entra'da yönetilen kimlikleri .

Ö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.

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;"

Seçenekler

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

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

Biçim

{
  "data-source": {
    "options": {
      "<key-name>": <string>
    }
  }
}

seçenekler: { set-session-context: boole }

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ı.

SQL Saklı Yordam Örneği:

CREATE PROC GetUser @userId INT AS
BEGIN
    -- Check if the current user has access to the requested userId
    IF SESSION_CONTEXT(N'user_role') = 'admin' 
        OR SESSION_CONTEXT(N'user_id') = @userId
    BEGIN
        SELECT Id, Name, Age, IsAdmin
        FROM Users
        WHERE Id = @userId;
    END
    ELSE
    BEGIN
        RAISERROR('Unauthorized access', 16, 1);
    END
END;

JSON Yapılandırması Örneği:

{
  "$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')",
    "options": {
      "set-session-context": true
    }
  },
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

Açıklama:

1. Saklı Yordam (GetUser):

   • Yordam, çağıranın admin rolüne sahip olup olmadığını veya sağlanan userId eşleşip eşleşmediğini doğrulamak için SESSION_CONTEXT denetler.
   • Yetkisiz erişim hatayla sonuçlanır.

2. JSON Yapılandırması:

   • set-session-context, kullanıcı meta verilerini erişim belirtecinden veritabanına geçirmek için etkinleştirilir.
   • parameters özelliği, saklı yordamın gerektirdiği userId parametresini eşler.
   • permissions bloğu yalnızca kimliği doğrulanmış kullanıcıların saklı yordamı yürütebilmesini sağlar.

Veri kaynağı dosyaları

Veri API oluşturucusu, farklı veri kaynakları için birden çok yapılandırma dosyasını destekler ve bunlardan biri runtime ayarlarını yöneten en üst düzey dosya olarak belirlenmiştir. Tüm yapılandırmalar aynı şemayı paylaşır ve herhangi bir dosyada hata olmadan runtime ayarlarına izin verir. Alt yapılandırmalar otomatik olarak birleştirilir, ancak döngüsel başvurulardan kaçınılmalıdır. Varlıklar daha iyi yönetim için ayrı dosyalara ayrılabilir, ancak varlıklar arasındaki ilişkiler aynı dosyada olmalıdır.

Biçim

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

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

• Her yapılandırma dosyası data-source özelliğini içermelidir.
• Her yapılandırma dosyası entities özelliğini içermelidir.
• runtime ayarı, diğer dosyalara dahil olsa bile yalnızca üst düzey yapılandırma dosyasından kullanılır.
• Alt yapılandırma dosyaları kendi alt dosyalarını da içerebilir.
• Yapılandırma dosyaları, istenildiği gibi alt klasörler halinde düzenlenebilir.
• Varlık adları tüm yapılandırma dosyalarında benzersiz olmalıdır.
• Farklı yapılandırma dosyalarındaki varlıklar arasındaki ilişkiler desteklenmez.

Örnekler

{
  "data-source-files": [
    "dab-config-2.json"
  ]
}

{
  "data-source-files": [
    "dab-config-2.json", 
    "dab-config-3.json"
  ]
}

Alt klasör söz dizimi de desteklenir:

{
  "data-source-files": [
    "dab-config-2.json",
    "my-folder/dab-config-3.json",
    "my-folder/my-other-folder/dab-config-4.json"
  ]
}

Çalışma zamanı

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": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    },
    "graphql": {
      "path": <string> (default: /graphql),
      "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": <integer; default: 100000>,
    "default-page-size": <integer; default: 100>,
    "max-response-size-mb": <integer; default: 158>
  },
  "telemetry": {
    "application-insights": {
      "connection-string": <string>,
      "enabled": <true> | <false> (default)
    }
  }
}

Özellikler

Ö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": -1 | <integer; default: 100000>,
      "default-page-size": -1 | <integer; default: 100>,
      "max-response-size-mb": <integer; default: 158>
    },
    "telemetry": {
      "application-insights": {
        "connection-string": "<connection-string>",
        "enabled": true
      }
    }
  }
}

GraphQL (çalışma zamanı)

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": <string> (default: /graphql),
      "enabled": <true> (default) | <false>,
      "depth-limit": <integer; default: none>,
      "allow-introspection": <true> (default) | <false>,
      "multiple-mutations": <object>
    }
  }
}

Özellikler

Etkin (GraphQL çalışma zamanı)

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": <true> (default) | <false>
    }
  }
}

Örnekler

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

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

Derinlik sınırı (GraphQL çalışma zamanı)

Bir sorgunun izin verilen en yüksek sorgu derinliği.

GraphQL'in iç içe sorguları ilişki tanımlarına göre işleyebilmesi inanılmaz bir özelliktir ve kullanıcıların tek bir sorguda karmaşık, ilgili verileri getirmesine olanak tanır. Ancak kullanıcılar iç içe sorguları eklemeye devam ettikçe sorgunun karmaşıklığı artar ve bu da hem veritabanının hem de API uç noktasının performansını ve güvenilirliğini tehlikeye atabilir. Bu durumu yönetmek için runtime/graphql/depth-limit özelliği bir GraphQL sorgusunun (ve mutasyonun) izin verilen en yüksek derinliğini ayarlar. Bu özellik, geliştiricilerin dengeyi aşmasına olanak tanıyarak kullanıcıların iç içe sorguların avantajlarından yararlanmasını sağlarken, sistemin performansını ve kalitesini tehlikeye atabilecek senaryoları önlemek için sınırlar getirir.

Örnekler

{
  "runtime": {
    "graphql": {
      "depth-limit": 2
    }
  }
}

Yol (GraphQL çalışma zamanı)

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 şeklindedir /graphql.

Biçim

{
  "runtime": {
    "graphql": {
      "path": <string> (default: /graphql)
    }
  }
}

Örnekler

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

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

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

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": <true> (default) | <false>
    }
  }
}

Ö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ı)

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

Biçim

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

Özellikler

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

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": <true> (default) | <false>
        }
      }
    }
  }
}

Özellikler

Örnekler

Aşağıda GraphQL çalışma zamanında birden çok mutasyonu etkinleştirme ve kullanma işlemleri gösterilmektedir. Bu durumda, create işlemi runtime.graphql.multiple-mutations.create.enabled özelliğini trueolarak ayarlayarak tek bir istekte birden çok kayıt oluşturulmasına izin verecek şekilde yapılandırılır.

Yapılandırma Örneği

Bu yapılandırma birden çok create mutasyona olanak tanır:

{
  "runtime": {
    "graphql": {
      "multiple-mutations": {
        "create": {
          "enabled": true
        }
      }
    }
  },
  "entities": {
    "User": {
      "source": "dbo.Users",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["create"]
        }
      ]
    }
  }
}

GraphQL Mutasyon Örneği

Aşağıdaki mutasyon, yukarıdaki yapılandırmayı kullanarak tek bir işlemde birden çok User kaydı oluşturur:

mutation {
  createUsers(input: [
    { name: "Alice", age: 30, isAdmin: true },
    { name: "Bob", age: 25, isAdmin: false },
    { name: "Charlie", age: 35, isAdmin: true }
  ]) {
    id
    name
    age
    isAdmin
  }
}

REST (çalışma zamanı)

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": <string> (default: /api),
      "enabled": <true> (default) | <false>,
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Özellikler

Etkin (REST çalışma zamanı)

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": <true> (default) | <false>,
    }
  }
}

Ö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ı)

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.

Biçim

{
  "runtime": {
    "rest": {
      "path": <string> (default: /api)
    }
  }
}

Örnekler

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

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

İstek Gövdesi Katı (REST Çalışma Zamanı)

Bu ayar REST mutasyon işlemleri için istek gövdesinin (örneğin, POST, PUT, PATCH) ne kadar kesin bir şekilde doğrulanıp doğrulan olmadığını denetler.

• true (varsayılan): İstek gövdesinde tablo sütunlarıyla eşleşmeyen ek alanlar BadRequest özel duruma neden olur.
• false: Ek alanlar yoksayılır ve yalnızca geçerli sütunlar işlenir.

bu ayar, istek gövdesi her zaman yoksayıldığı için istekler için geçerli .

Belirli Sütun Yapılandırmalarında Davranış

• default() değerine sahip sütunlar, INSERT sırasında yalnızca yükteki değerleri nullolduğunda yoksayılır. Default() değerine sahip sütunlar, yük değerinden bağımsız olarak UPDATE sırasında yoksayılmaz.
• Hesaplanan sütunlar her zaman yoksayılır.
• Otomatik oluşturulan sütunlar her zaman yoksayılır.

Biçim

{
  "runtime": {
    "rest": {
      "request-body-strict": <true> (default) | <false>
    }
  }
}

Örnekler

CREATE TABLE Users (
    Id INT PRIMARY KEY IDENTITY,
    Name NVARCHAR(50) NOT NULL,
    Age INT DEFAULT 18,
    IsAdmin BIT DEFAULT 0,
    IsMinor AS IIF(Age <= 18, 1, 0)
);

Örnek Yapılandırma

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

request-body-strict: false ile INSERT Davranışı

İstek Yükü:

{
  "Id": 999,
  "Name": "Alice",
  "Age": null,
  "IsAdmin": null,
  "IsMinor": false,
  "ExtraField": "ignored"
}

Sonuçta Elde Edilen Insert Deyimi:

INSERT INTO Users (Name) VALUES ('Alice');
-- Default values for Age (18) and IsAdmin (0) are applied by the database.
-- IsMinor is ignored because it’s a computed column.
-- ExtraField is ignored.
-- The database generates the Id value.

Yanıt Yükü:

{
  "Id": 1,          // Auto-generated by the database
  "Name": "Alice",
  "Age": 18,        // Default applied
  "IsAdmin": false, // Default applied
  "IsMinor": true   // Computed
}

request-body-strict: false ile UPDATE Davranışı

İstek Yükü:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,     // explicitely set to 'null'
  "IsMinor": true, // ignored because computed
  "ExtraField": "ignored"
}

Sonuçta Elde Edilen Güncelleştirme Deyimi:

UPDATE Users
SET Name = 'Alice Updated', Age = NULL
WHERE Id = 1;
-- IsMinor and ExtraField are ignored.

Yanıt Yükü:

{
  "Id": 1,
  "Name": "Alice Updated",
  "Age": null,
  "IsAdmin": false,
  "IsMinor": false // Recomputed by the database (false when age is `null`)
}

Konak (çalışma zamanı)

Ç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",
      "max-response-size-mb": <integer; default: 158>,
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      },
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Özellikler

Ö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ı)

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 şudur: 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.

Biçim

{
  "runtime": {
    "host": {
      "mode": "production" (default) | "development"
    }
  }
}

Değer

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

Davranış

• Swagger yalnızca development modunda kullanılabilir.
• Yalnızca development modunda Muzlu Kek Pop kullanılabilir.

En büyük yanıt boyutu (Çalışma Zamanı)

Herhangi bir sonuç için en büyük boyutu (megabayt cinsinden) ayarlar. Bu ayar, kullanıcıların temel alınan veri kaynaklarından veri akışı yaparken konak platformlarının belleğinin işleyebileceği veri miktarını yapılandırmasına olanak tanır.

Kullanıcılar büyük sonuç kümeleri istediğinde, veritabanını ve Veri API'sini oluşturucuyu zorlayabilir. Bu sorunu çözmek için max-response-size-mb, geliştiricilerin veri kaynağından veri akışı yapılırken megabayt cinsinden ölçülen maksimum yanıt boyutunu sınırlamasına olanak tanır. Bu sınır, satır sayısını değil genel veri boyutunu temel alır. Sütunların boyutu farklılık gösterebileceğinden, bazı sütunlar (metin, ikili, XML veya JSON gibi) her biri 2 GB'a kadar tutabilir ve tek tek satırların büyük olması olasıdır. Bu ayar, geliştiricilerin yanıt boyutlarına dokunarak ve farklı veri türleri için esnekliği koruyarak sistem aşırı yüklemelerini önleyerek uç noktalarını korumalarına yardımcı olur.

İzin verilen değerler

Biçim

{
  "runtime": {
    "host": {
      "max-response-size-mb": <integer; default: 158>
    }
  }
}

CORS (Konak çalışma zamanı)

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

Biçim

{
  "runtime": {
    "host": {
      "cors": {
        "origins": ["<array-of-strings>"],
        "allow-credentials": <true> | <false> (default)
      }
    }
  }
}

Özellikler

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

True ise, Access-Control-Allow-Credentials CORS üst bilgisini ayarlar.

Biçim

{
  "runtime": {
    "host": {
      "cors": {
        "allow-credentials": <true> (default) | <false>
      }
    }
  }
}

Origins (Konak çalışma zamanı)

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": ["<array-of-strings>"]
      }
    }
  }
}

Ö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ı)

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

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<string>",
          "issuer": "<string>"
        }
      }
    }
  }
}

Özellikler

Kimlik Doğrulaması ve müşteri sorumlulukları

Veri API oluşturucusu daha geniş bir güvenlik işlem hattı içinde çalışacak şekilde tasarlanmıştır ve istekleri işlemeden önce yapılandırılması gereken önemli adımlar vardır. Veri API'si oluşturucusunun, güvenilir bir kimlik sağlayıcısı (örneğin, Entra Id) tarafından sağlanan geçerli bir JWT belirtecini temel alarak doğrudan çağıranın (web uygulamanız gibi) değil, son kullanıcının kimliğini doğrulamadığını anlamak önemlidir. bir istek Veri API oluşturucusunun üzerine geldiğinde JWT belirtecinin geçerli olduğunu varsayar ve belirli talepler gibi yapılandırdığınız tüm önkoşullara karşı denetler. Daha sonra kullanıcının erişebileceği veya değiştirebileceği özellikleri belirlemek için yetkilendirme kuralları uygulanır.

Yetkilendirme geçtikten sonra, Veri API oluşturucusu bağlantı dizesinde belirtilen hesabı kullanarak isteği yürütür. Bu hesap genellikle çeşitli kullanıcı isteklerini işlemek için yükseltilmiş izinler gerektirdiğinden, riski azaltmak için erişim haklarını en aza indirmek önemlidir. Ön uç web uygulamanızla API uç noktası arasında Özel Bağlantı yapılandırarak ve Veri API'sini barındıran makineyi sağlamlaştırarak mimarinizin güvenliğini sağlamanızı öneririz. Bu ölçüler, ortamınızın güvenli kalmasını sağlamaya, verilerinizi korumaya ve hassas bilgilere erişmek, bunları değiştirmek veya dışarı sızmak için yararlanabilecek güvenlik açıklarını en aza indirmeye yardımcı olur.

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

authentication.provider yapılandırmasındaki host 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.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...
      }
    }
  }
}

Değer

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

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

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 audience kiracısına karşı alınan JWT belirtecini doğrulamak için issuer ve AzureAD belirtmelidir.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "StaticWebApps" (default) | ...,
        "jwt": {
          "audience": "<client-id>",
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Özellikler

Ö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.

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ı)

JWT belirtecinin hedef kitlesi.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "audience": "<client-id>"
        }
      }
    }
  }
}

Veren (Konak çalışma zamanı)

JWT belirteci için veren.

Biçim

{
  "runtime": {
    "host": {
      "authentication": {
        "jwt": {
          "issuer": "<issuer-url>"
        }
      }
    }
  }
}

Sayfalandırma (Çalışma Zamanı)

REST ve GraphQL uç noktaları için sayfalandırma sınırları yapılandırılır.

Biçim

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>,
      "default-page-size": <integer; default: 100>
    }
  }
}

Özellikler

Örnek Yapılandırma

{
  "runtime": {
    "pagination": {
      "max-page-size": 1000,
      "default-page-size": 2
    }
  },
  "entities": {
    "Users": {
      "source": "dbo.Users",
      "permissions": [
        {
          "actions": ["read"],
          "role": "anonymous"
        }
      ]
    }
  }
}

REST Sayfalandırma Örneği

Bu örnekte REST GET isteği https://localhost:5001/api/users verilmesi, default-page-size 2 olarak ayarlandığından value dizisinde iki kayıt döndürür. Daha fazla sonuç varsa, Veri API oluşturucusu yanıta bir nextLink içerir. nextLink, sonraki veri sayfasını almak için bir $after parametresi içerir.

İstek:

GET https://localhost:5001/api/users

Yanıt:

{
  "value": [
    {
      "Id": 1,
      "Name": "Alice",
      "Age": 30,
      "IsAdmin": true,
      "IsMinor": false
    },
    {
      "Id": 2,
      "Name": "Bob",
      "Age": 17,
      "IsAdmin": false,
      "IsMinor": true
    }
  ],
  "nextLink": "https://localhost:5001/api/users?$after=W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
}

nextLinkkullanarak istemci sonraki sonuç kümesini getirebilir.

GraphQL Sayfalandırma Örneği

GraphQL için sayfalandırma için hasNextPage ve endCursor alanlarını kullanın. Bu alanlar daha fazla sonuç olup olmadığını gösterir ve sonraki sayfayı getirmek için bir imleç sağlar.

Sorgu:

query {
  users {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Yanıt:

{
  "data": {
    "users": {
      "items": [
        {
          "Id": 1,
          "Name": "Alice",
          "Age": 30,
          "IsAdmin": true,
          "IsMinor": false
        },
        {
          "Id": 2,
          "Name": "Bob",
          "Age": 17,
          "IsAdmin": false,
          "IsMinor": true
        }
      ],
      "hasNextPage": true,
      "endCursor": "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI=="
    }
  }
}

Sonraki sayfayı getirmek için sonraki sorguya endCursor değerini ekleyin:

İmleçli Sorgu:

query {
  users(after: "W3siRW50aXR5TmFtZSI6InVzZXJzIiwiRmllbGROYW1lI==") {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
    hasNextPage
    endCursor
  }
}

Sayfa Boyutunu Ayarlama

REST ve GraphQL, $limit (REST) veya first (GraphQL) kullanarak sorgu başına sonuç sayısını ayarlamaya olanak sağlar.

Örnek REST Sorgusu:

GET https://localhost:5001/api/users?$limit=5

Örnek GraphQL Sorgusu:

query {
  users(first: 5) {
    items {
      Id
      Name
      Age
      IsAdmin
      IsMinor
    }
  }
}

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

REST veya GraphQL tarafından döndürülen en üst düzey kayıt sayısı üst sınırını ayarlar. Kullanıcı max-page-size'den fazlasını isterse sonuçlar max-page-sizeile eşlenir.

İzin verilen değerler

Biçim

{
  "runtime": {
    "pagination": {
      "max-page-size": <integer; default: 100000>
    }
  }
}

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

Sayfalandırma etkinleştirildiğinde, ancak açık sayfa boyutu sağlanmadığında döndürülen varsayılan en üst düzey kayıt sayısını ayarlar.

İzin verilen değerler

Önbellek (çalışma zamanı)

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

Biçim

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

Özellikler

Ö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ı)

Tüm varlıklar için genel olarak önbelleğe almayı etkinleştirir. varsayılan değeridir 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ı)

Ö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ı)

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

Biçim

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": <true; default: true> | <false>,
        "connection-string": <string>
      }
    }
  }
}

Application Insights (Telemetri çalışma zamanı)

Etkin (Application Insights telemetrisi)

Bağlantı dizesi (Application Insights telemetrisi)

Varlık

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: true> | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      },
      "graphql": {
        "enabled": <true; default: true> | <false>,
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": <"query" | "mutation"; default: "query">
      },
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>,
        "parameters": {
          "<parameter-name>": <string | number | boolean>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "relationships": {
        "<relationship-name>": {
          "cardinality": <"one" | "many">,
          "target.entity": <string>,
          "source.fields": <array of strings>,
          "target.fields": <array of strings>,
          "linking.object": <string>,
          "linking.source.fields": <array of strings>,
          "linking.target.fields": <array of strings>
        }
      },
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role-name">,
          "actions": <array of strings>,
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

Özellikler

Örnekler

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

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    }
  }
}

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": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table",
        "key-fields": ["Id"],
        "parameters": {} // only when source.type = stored-procedure
      },
      "rest": {
        "enabled": true,
        "path": "/users",
        "methods": [] // only when source.type = stored-procedure
      },
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "User",
          "plural": "Users"
        },
        "operation": "query"
      },
      "mappings": {
        "id": "Id",
        "name": "Name",
        "age": "Age",
        "isAdmin": "IsAdmin"
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"],  // "execute" only when source.type = stored-procedure
          "fields": {
            "include": ["id", "name", "age", "isAdmin"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userId eq @item.id"
          }
        },
        {
          "role": "admin",
          "actions": ["create", "read", "update", "delete"],
          "fields": {
            "include": ["*"],
            "exclude": []
          },
          "policy": {
            "database": "@claims.userRole eq 'UserAdmin'"
          }
        }
      ]
    }
  }
}

Kaynak

{entity}.source yapılandırması, API tarafından kullanıma sunulan varlığı ve temel alınan veritabanı nesnesini bağlar. 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 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: "source": "dbo.User".

Biçim

{
  "entities": {
    "<entity-name>": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">, 
        "key-fields": <array of strings>,
        "parameters": {  // only when source.type = stored-procedure
          "<name>": <string | number | boolean>
        }
      }
    }
  }
}

Özellikler

Örnekler

1. Basit Tablo Eşlemesi:

Bu örnekte, bir User varlığının dbo.Usersbir kaynak tabloyla nasıl ilişkilendirilecekleri gösterilmektedir.

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Yapılandırma

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Saklı Yordam Örneği:

Bu örnekte, bir User varlığının kaynak proc dbo.GetUsersile nasıl ilişkilendirilecekleri gösterilmektedir.

SQL

CREATE PROCEDURE GetUsers 
     @IsAdmin BIT 
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

Yapılandırma

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age",
        "IsAdmin": "isAdmin"
      }
    }
  }
}

saklı yordamlar için mappings özelliği isteğe bağlıdır.

Nesne

Kullanılacak veritabanı nesnesinin adı. Nesne dbo şemasına aitse, şemanın belirtilmesi isteğe bağlıdır. Ayrıca, nesne adlarının etrafındaki köşeli ayraçlar (örneğin, [dbo].[Users] ve dbo.Users) kullanılabilir veya atlanabilir.

Örnekler

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Yapılandırma

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

Şema ve Köşeli Ayraç olmadan Alternatif Gösterimi:

Tablo dbo şemasındaysa, şemayı veya köşeli ayraçları atabilirsiniz:

{
  "entities": {
    "User": {
      "source": {
        "object": "Users",
        "type": "table"
      }
    }
  }
}

Tür (varlıklar)

type özelliği, view, tableve stored-proceduredahil olmak üzere varlığın arkasındaki veritabanı nesnesinin türünü tanımlar. Bu özellik gereklidir ve varsayılan değeri yoktur.

Biçim

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

Değer

Örnekler

1. Tablo Örneği:

SQL

CREATE TABLE dbo.Users (
  Id INT PRIMARY KEY,
  Name NVARCHAR(100),
  Age INT,
  IsAdmin BIT
);

Yapılandırma

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      }
    }
  }
}

2. Görünüm Örneği:

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

Yapılandırma

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      },
      "mappings": {
        "Id": "id",
        "Name": "name",
        "Age": "age"
      }
    }
  }
}

Not:key-fields belirtme, görünümler için önemlidir çünkü bunlar doğal birincil anahtarlara sahip değildir.

3. Saklı Yordam Örneği:

SQL

CREATE PROCEDURE dbo.GetUsers (@IsAdmin BIT)
AS
SELECT Id, Name, Age, IsAdmin
FROM dbo.Users
WHERE IsAdmin = @IsAdmin;

Yapılandırma

{
  "entities": {
    "User": {
      "source": {
        "type": "stored-procedure",
        "object": "GetUsers",
        "parameters": {
          "IsAdmin": "boolean"
        }
      }
    }
  }
}

Anahtar alanları

{entity}.key-fields özelliği özellikle görünümler tarafından yedeklenen varlıklar için gereklidir, bu nedenle Data API Builder tek bir öğeyi tanımlamayı ve döndürmeyi bilir. type key-fieldsbelirtilmeden view olarak ayarlanırsa, altyapı başlamayı reddeder. Bu özelliğe tablolar ve saklı yordamlar ile izin verilir, ancak bu durumlarda kullanılmaz.

Biçim

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": <array of strings>
      }
    }
  }
}

Örnek: Anahtar Alanları ile Görünüm

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

SQL

CREATE VIEW dbo.AdminUsers AS
SELECT Id, Name, Age
FROM dbo.Users
WHERE IsAdmin = 1;

Yapılandırma

{
  "entities": {
    "AdminUsers": {
      "source": {
        "object": "dbo.AdminUsers",
        "type": "view",
        "key-fields": ["Id"]
      }
    }
  }
}

Parametre

entities.{entity}.source içindeki parameters özelliği, saklı yordamlar tarafından yedeklenen varlıklar için kullanılır. Saklı yordamın gerektirdiği parametre adlarının ve veri türlerinin düzgün eşlanmasını sağlar.

Biçim

{
  "entities": {
    "<entity-name>": {
      "source": {
        "type": "stored-procedure",
        "parameters": {
          "<parameter-name-1>": <string | number | boolean>,
          "<parameter-name-2>": <string | number | boolean>
        }
      }
    }
  }
}

Örnek 1: Parametresiz Saklı Yordam

SQL

CREATE PROCEDURE dbo.GetUsers AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users;

Yapılandırma

{
  "entities": {
    "Users": {
      "source": {
        "object": "dbo.GetUsers",
        "type": "stored-procedure"
      }
    }
  }
}

Örnek 2: Parametrelerle Saklı Yordam

SQL

CREATE PROCEDURE dbo.GetUser (@userId INT) AS
SELECT Id, Name, Age, IsAdmin FROM dbo.Users
WHERE Id = @userId;

Yapılandırma

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      }
    }
  }
}

İzinler

Bu bölüm, ilgili varlığa kimlerin erişebileceğini ve hangi eylemlere izin verilip verilmeyebileceğini tanımlar. İzinler roller ve CRUD işlemleri açısından tanımlanır: create, read, updateve delete. permissions bölümü, hangi rollerin ilgili varlığa erişebileceğini ve hangi eylemleri kullanabileceğini belirtir.

Biçim

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

Örnekler

Örnek 1: Kullanıcı Varlığında Anonim Rol

Bu örnekte, anonymous rolü User varlığındaki tüm olası eylemlere erişimle tanımlanır.

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

Örnek 2: Anonim Rol için Karma Eylemler

Bu örnekte, User varlığı için dize ve nesne dizisi eylemlerinin nasıl karıştırılması gösterilmektedir.

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

anonim rol: Anonim kullanıcıların varsayımsal bir hassas alan dışındaki tüm alanları okumasına izin verir (örneğin, ). "exclude": ["secret-field"] ile "include": ["*"] kullanılması, diğer tüm alanlara erişim izni verirken secret-field gizler.

Kimliği Doğrulanmış Rol: Kimliği doğrulanmış kullanıcıların belirli alanları okumasına ve güncelleştirmesine izin verir. Örneğin, açıkça id, nameve age dahil ancak isAdmin dışlamak, dışlamaların eklemeleri nasıl geçersiz kılmasını gösterebilir.

Yönetici Rolü: Yöneticiler, dışlama olmadan tüm alanlarda tüm işlemleri (*) gerçekleştirebilir. Boş bir "exclude": [] dizisiyle "include": ["*"] belirtilmesi tüm alanlara erişim verir.

Bu yapılandırma:

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

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

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

Bu kurulumu da göz önünde bulundurun:

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

Bu, hiçbir alanın açıkça dahil olmadığını ve tüm alanların dışlandığını belirtir ve bu da genellikle erişimi tamamen kısıtlar.

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 belirli eylemleri (varlık oluşturma gibi) gerçekleştirdiği senaryolarda kullanılabilir.

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

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

Bu kurulum yalnızca Id ve Name alanlarını dahil etmeye çalışır, ancak excludejoker karakteri nedeniyle tüm alanları dışlar.

Aynı mantığı ifade etmenin başka bir yolu da şu olabilir:

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

exclude include'den öncelikli olduğu düşünüldüğünde, exclude: ["*"] belirtilmesi, includeiçindekiler bile dahil tüm alanların dışlandığı anlamına gelir. Bu nedenle, ilk bakışta bu yapılandırma herhangi bir alanın erişilebilir olmasını engelliyor gibi görünebilir.

Ters: Amaç yalnızca Id ve Name alanlarına erişim vermekse, dışlama joker karakteri kullanmadan yalnızca include bölümündeki alanları belirtmek daha açık ve daha güvenilirdir:

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

Özellikler

Rol

Tanımlanan iznin uygulandığı rolün adını içeren dize. 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 REST ve GraphQL uç noktaları aracılığıyla nasıl erişilebileceğini belirleyen bir rol kümesi ve ilişkili izinler tanımlayabilirsiniz. Roller ekli değildir.

Data API Builder istekleri tek bir rol bağlamında değerlendirir:

Biçim

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": <array of strings>,
            "exclude": <array of strings>
          }
        }
      ]
    }
  }
}

Örnekler

Bu örnek, User varlığında yalnızca read izinlerine sahip reader adlı bir rolü tanımlar.

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

geçerli bir erişim belirteci sunulduğunda ve X-MS-API-ROLE HTTP üst bilgisinin dahil erişim belirtecinin rol taleplerinde de yer alan bir kullanıcı rolü belirterek <custom-role> kullanabilirsiniz. Aşağıda, farklı diller kullanan localhost'deki REST uç nokta tabanı /api hem yetkilendirme taşıyıcı belirteci hem de X-MS-API-ROLE üst bilgisi dahil olmak üzere User varlığa yönelik GET isteklerine örnekler verilmiştir.

GET https://localhost:5001/api/User
Authorization: Bearer <your_access_token>
X-MS-API-ROLE: custom-role

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<your_access_token>");
client.DefaultRequestHeaders.Add("X-MS-API-ROLE", "custom-role");
var response = await client.GetAsync("https://localhost:5001/api/User");

const response = await fetch('https://localhost:5001/api/User', {
  headers: { 
    "Authorization": "Bearer <your_access_token>",
    "X-MS-API-ROLE": "custom-role"
  }
});

import requests

headers = {
  "Authorization": "Bearer <your_access_token>",
  "X-MS-API-ROLE": "custom-role"
}
response = requests.get('https://localhost:5001/api/User', headers=headers)
print(response.json())

Eylemler (dize dizisi)

İ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 kullanabilir. Saklı yordamlar için roller yalnızca execute eylemine sahip olabilir.

Örnekler

Bu örnek, contributor adlı bir role create ve read izinleri verir ve User varlığındaki auditor adlı bir role delete izinleri verir.

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

Başka bir örnek:

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "contributor",
          "actions": ["read", "create"]
        }
      ]
    }
  }
}

Eylemler (nesne dizisi)

İlişkili rol için izin verilen işlemleri ayrıntılandıran bir eylem nesneleri dizisi. table ve view nesneleri için roller create, read, updateveya deleteherhangi bir bileşimini kullanabilir. Saklı yordamlar için yalnızca execute izin verilir.

Biçim

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

Özellikler

Örnek

Bu örnek, alan ve ilke kısıtlamalarıyla User varlığındaki auditor rolüne yalnızca read izin verir.

{
  "entities": {
    "User": {
      "permissions": [
        {
          "role": "auditor",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["*"],
                "exclude": ["last_login"]
              },
              "policy": {
                "database": "@item.IsAdmin eq false"
              }
            }
          ]
        }
      ]
    }
  }
}

Eylem

Veritabanı nesnesinde izin verilen işlemi belirtir.

Değer

Biçim

{
  "entities": {
    "<entity-name>": {
      "permissions": [
        {
          "role": "<role>",
          "actions": [
            {
              "action": "<string>",
              "fields": {
                "include": [/* fields */],
                "exclude": [/* fields */]
              },
              "policy": {
                "database": "<predicate>"
              }
            }
          ]
        }
      ]
    }
  }
}

Örnek

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

{
  "entities": {
    "User": {
      "source": {
        "object": "dbo.Users",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        }
      ]
    },
    "GetUser": {
      "source": {
        "object": "dbo.GetUser",
        "type": "stored-procedure",
        "parameters": {
          "userId": "number"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ]
    }
  }
}

Alanları

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": {
    <string>: {
      "permissions": [
        {
          "role": <string>,
          "actions": [
            {
              "action": <string>,
              "fields": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": <object>
            }
          ]
        }
      ]
    }
  }
}

Ö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. * bölümündeki joker karakter include 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

policybaşına tanımlanan action 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": <object>,
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

Özellikler

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.

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:

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

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

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>": <string>,
        "<field-2-name>": <string>,
        "<field-3-name>": <string>
      }
    }
  }
}

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 (EmployeeId) alan diğer adı @claims.userId eq @item.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ı

policybaşına tanımlanan action 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": {
                "include": <array of strings>,
                "exclude": <array of strings>
              },
              "policy": {
                "database": <string>
              }
            }
          ]
        }
      ]
    }
  }
}

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.

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:

Ö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.

GraphQL (varlıklar)

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 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": <string>,
          "plural": <string>
        },
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "enabled": <boolean>,
        "type": <string-or-object>,
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Özellikler

Ö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ığı)

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": {
    <entity-name>: {
      "graphql": {
        "type": <string>
      }
    }
  }
}

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

Özellikler

Ö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ığı)

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.

Eksikse, varsayılan operationmutationolur.

Biçim

{
  "entities": {
    "<entity-name>": {
      "graphql": {
        "operation": "query" (default) | "mutation"
      }
    }
  }
}

Değer

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

Ö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!]!
}

Etkin (GraphQL varlığı)

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> (default) | <false>
      }
    }
  }
}

REST (varlıklar)

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": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

Özellikler

Ö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ığı)

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.

Biçim

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

Yol (REST varlığı)

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 şeklindedir /<entity-name>.

Biçim

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "path": <string; default: "<entity-name>">
      }
    }
  }
}

Örnekler

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

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

Yöntemler (REST varlığı)

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:

Ö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": "number"
        }
      },
      "rest": {
        "path": "/best-selling-authors",
        "methods": [ "get" ]
      }
    }
  }
}

Eşlemeler (varlıklar)

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.

Biçim

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

Örnekler

Bu örnekte, veritabanı nesnesi sku_titledbo.magazines 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)

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ü.

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.

Biçim

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

Özellikler

Ö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 varlığıyla Book ilişkisine sahip bir ilişki örneğini ele alalım. Burada kardinalite manyolarak ayarlanır. Her Category varlığı yalnızca tek bir Book varlığıyla ilişkilendirilirken, her Book birden çok ilişkili Category 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 (id) Category 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 (category_id) Book 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 (category_id) Book alanının ilgili hedef varlığın (id) Category 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 (id) hem de hedef (Book) varlıklarının birincil tanımlayıcısını (Author) 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 id varlığının Book alanına başvurduğunu belirtir ve linking.target.fields bağlama nesnesinin author_id alanının id varlığının Author 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

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:

Hedef varlık

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

Kaynak alanlar

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.

Hedef alanlar

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.

Nesne veya varlık bağlama

Ç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

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

Hedef alanları bağlama

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

Önbellek (varlıklar)

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

Biçim

You're right; the formatting doesn't match your style. Here’s the corrected version following your preferred documentation format:

```json
{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <true> (default) | <false>,
        "ttl-seconds": <integer; default: 5>
      }
    }
  }
}

Özellikler

Ö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ığı)

Varlık için önbelleğe almayı etkinleştirir.

Veritabanı Nesnesi Desteği

HTTP Üst Bilgi Desteği

Biçim

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "enabled": <boolean> (default: false)
      }
    }
  }
}

Örnekler

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

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

Saniye olarak TTL (Önbellek varlığı)

Ö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

{
  "entities": {
    "<entity-name>": {
      "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
      }
    }
  }
}

İlgili içerik

• İşlevleri başvurusu
• Komut satırı arabirimi (CLI) başvurusu