A Data API Builder konfigurációs sémájának referenciája

A Data API Builder motorjának konfigurációs fájlra van szüksége. A Data API Builder konfigurációs fájlja strukturált és átfogó megközelítést biztosít az API beállításához, amely mindent részletesen tartalmaz a környezeti változóktól az entitásspecifikus konfigurációkig. Ez a JSON formátumú dokumentum egy $schema tulajdonsággal kezdődik. Ez a beállítás ellenőrzi a dokumentumot.

A tulajdonságok database-type és connection-string biztosítják az adatbázisrendszerekkel való zökkenőmentes integrációt az Azure SQL Database-től a Cosmos DB NoSQL API-ig.

A konfigurációs fájl tartalmazhat olyan beállításokat, mint például:

• Adatbázis-szolgáltatás és kapcsolatadatok
• Globális és futtatókörnyezeti konfigurációs beállítások
• Közzétett entitások készlete
• Hitelesítési módszer
• Az identitásokhoz való hozzáféréshez szükséges biztonsági szabályok
• Névleképezési szabályok az API és az adatbázis között
• Nem következtethető entitások közötti kapcsolatok
• Egyedi funkciók adott adatbázis-szolgáltatásokhoz

Szintaxis áttekintése

Íme egy konfigurációs fájl elsődleges "szakaszainak" gyors lebontása.

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

Legfelső szintű tulajdonságok

A táblaformátum legfelső szintű tulajdonságainak leírása:

Mintakonfigurációk

Íme egy mintakonfigurációs fájl, amely csak egyetlen egyszerű entitás szükséges tulajdonságait tartalmazza. Ez a minta egy minimális forgatókönyv szemléltetésére szolgál.

{
  "$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": ["*"]
        }
      ]
    }
  }
}

Egy összetettebb forgatókönyvre példaként tekintse meg a végpontok közötti konfigurációs.

Környezetben

A Data API Builder konfigurációs fájlja olyan forgatókönyveket támogat, ahol több környezetet kell támogatnia, hasonlóan a ASP.NET Core appSettings.json fájlhoz. A keretrendszer három közös környezeti értéket biztosít; Development, Stagingés Production; de bármilyen környezeti értéket használhat. A Data API Builder által használt környezetet a DAB_ENVIRONMENT környezeti változó használatával kell konfigurálni.

Vegyünk egy példát, ahol alapkonfigurációt és fejlesztésspecifikus konfigurációt szeretne. Ehhez a példához két konfigurációs fájl szükséges:

A fejlesztésspecifikus konfiguráció használatához a DAB_ENVIRONMENT környezeti változót Developmentértékre kell állítania.

A környezetspecifikus konfigurációs fájlok felülbírálják az alapkonfigurációs fájl tulajdonságértékét. Ebben a példában, ha a connection-string érték mindkét fájlban be van állítva, a *.Development.json fájl értékét használja a rendszer.

Ebben a mátrixban jobban megismerheti, hogy melyik értéket használja a rendszer attól függően, hogy hol van megadva (vagy nincs megadva) a fájlban.

Több konfigurációs fájl használatára vonatkozó példa: a Data API Builder használata környezetekkel.

Konfigurációs tulajdonságok

Ez a szakasz tartalmazza a konfigurációs fájlhoz elérhető összes lehetséges konfigurációs tulajdonságot.

Séma

Minden konfigurációs fájl egy $schema tulajdonsággal kezdődik, amely megadja az ellenőrzéshez JSON-séma.

Formátum

{
  "$schema": <string>
}

Példák

A sémafájlok bizonyos URL-címeken 0.3.7-alpha verziókhoz érhetők el, így a megfelelő verziót vagy a legújabb elérhető sémát használhatja.

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

Cserélje le VERSION-suffix a kívánt verzióra.

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

A séma legújabb verziója mindig elérhető https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json.

Íme néhány példa az érvényes sémaértékekre.

Adatforrás

A data-source szakasz a kapcsolati sztringen keresztül határozza meg az adatbázist és az adatbázishoz való hozzáférést. Az adatbázis-beállításokat is meghatározza. A data-source tulajdonság konfigurálja a háttéradatbázishoz való csatlakozáshoz szükséges hitelesítő adatokat. A data-source szakasz a háttéradatbázis-kapcsolatot vázolja fel, a database-type és a connection-stringmegadásával.

Formátum

{
  "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>
    }
  }
}

Kellékek

Adatbázis típusa

Az adatforrásként használni kívánt adatbázis típusának megadására szolgáló enumerálási sztring.

Formátum

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

Értékek beírása

A type tulajdonság a háttéradatbázis típusát jelzi.

Kapcsolati sztring

Egy sztring érték, amely egy érvényes kapcsolati sztringet tartalmaz a céladatbázis-szolgáltatáshoz való csatlakozáshoz. A háttéradatbázishoz való csatlakozáshoz ADO.NET kapcsolati sztring. További információ: ADO.NET kapcsolati sztringek.

Formátum

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

Kapcsolat rugalmassága

A Data API Builder automatikusan újrapróbálkozza az adatbázis-kérelmeket az átmeneti hibák észlelése után. Az újrapróbálkozási logika egy exponenciális backoff stratégiát követ, amelyben az újrapróbálkozások maximális száma öt. A későbbi kérések kiszámítása utáni újrapróbálkozási időtartam ezzel a képlettel történik (feltéve, hogy az újrapróbálkozási kísérlet r): $r^2$

Ezzel a képlettel másodpercek alatt kiszámíthatja az egyes újrapróbálkozási kísérletek idejét.

Azure SQL és SQL Server

A Data API Builder a SqlClient kódtár használatával csatlakozik az Azure SQL-hez vagy az SQL Serverhez a konfigurációs fájlban megadott kapcsolati sztring használatával. A támogatott kapcsolati sztringbeállítások listája itt érhető el: SqlConnection.ConnectionString tulajdonság.

A Data API Builder a felügyeltszolgáltatás-identitások (MSI) használatával is csatlakozhat a céladatbázishoz, ha a Data API Builder az Azure-ban van üzemeltetve. A DefaultAzureCredential kódtárban definiált Azure.Identity ismert identitások használatával csatlakozik, ha nem ad meg felhasználónevet vagy jelszót a kapcsolati sztringben. További információ: DefaultAzureCredential példák.

• felhasználó által hozzárendelt felügyelt identitás (UMI): Fűzze hozzá a hitelesítési és felhasználói azonosító tulajdonságait a kapcsolati sztringhez, miközben a felhasználó által hozzárendelt felügyelt identitás ügyfélazonosítójában a következőt helyettesíti: Authentication=Active Directory Managed Identity; User Id=<UMI_CLIENT_ID>;.
• rendszer által hozzárendelt felügyelt identitás (SMI): Fűzze hozzá a Hitelesítési tulajdonságot, és zárja ki a UserId és Jelszó argumentumokat a kapcsolati sztringből: Authentication=Active Directory Managed Identity;. A UserId és Jelszó kapcsolati sztring tulajdonságainak hiánya jelzi a DAB-nak a hitelesítést egy rendszer által hozzárendelt felügyelt identitással.

A felügyeltszolgáltatás-identitás Azure SQL-sel vagy SQL Serverrel való konfigurálásáról további információt Felügyelt identitások az Azure SQL-hez készült Microsoft Entracímű cikkben talál.

Példák

A kapcsolati sztringhez használt érték nagyban függ a forgatókönyvben használt adatbázis-szolgáltatástól. A kapcsolati sztringet mindig egy környezeti változóban tárolhatja, és a @env() függvénnyel érheti el.

Ezek a minták csak szemléltetik az egyes adatbázistípusok konfigurálását. Előfordulhat, hogy a forgatókönyv egyedi, de ez a minta jó kiindulási hely. Cserélje le a helyőrzőket, például myserver, myDataBase, myloginés myPassword a környezetre jellemző tényleges értékekkel.

• mssql

  "data-source": {
    "database-type": "mssql",
    "connection-string": "$env('my-connection-string')",
    "options": {
      "set-session-context": true
    }
  }
  

  • Tipikus kapcsolati sztringformátum: "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')"
  }
  

  • Tipikus kapcsolati sztringformátum: "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')"
  }
  

  • Tipikus kapcsolati sztringformátum: "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"
    }
  }
  

  • Tipikus kapcsolati sztringformátum: "AccountEndpoint=https://mycosmosdb.documents.azure.com:443/;AccountKey=myAccountKey;"

• cosmosdb_postgresql

  "data-source": {
    "database-type": "cosmosdb_postgresql",
    "connection-string": "$env('my-connection-string')"
  }
  

  • Tipikus kapcsolati sztringformátum: "Host=mycosmosdb.postgres.database.azure.com;Database=myDataBase;Username=mylogin@mycosmosdb;Password=myPassword;Port=5432;SSL Mode=Require;"

Beállítások

Az adott adatbázis-kapcsolatok extra kulcs-érték paramétereinek opcionális szakasza.

Az, hogy a options szakasz szükséges-e vagy sem, nagyrészt a használt adatbázis-szolgáltatástól függ.

Formátum

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

options: { set-session-context: boolean }

Az Azure SQL és az SQL Server esetében a Data API Builder kihasználhatja a SESSION_CONTEXT, hogy felhasználó által megadott metaadatokat küldjön a mögöttes adatbázisba. Ezek a metaadatok a Hozzáférési jogkivonatban található jogcímek alapján érhetők el a Data API Builder számára. A SESSION_CONTEXT adatok az adatbázis-kapcsolat során mindaddig elérhetők az adatbázis számára, amíg a kapcsolat be nem záródik. További információ: munkamenet-környezet.

Sql-alapú tárolt eljárás – példa:

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;

Példa JSON-konfigurációra:

{
  "$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"]
        }
      ]
    }
  }
}

Magyarázat:

1. tárolt eljárás (GetUser):

   • Az eljárás ellenőrzi a SESSION_CONTEXT annak ellenőrzéséhez, hogy a hívó rendelkezik-e admin szerepkörével, vagy megfelel-e a megadott userId.
   • A jogosulatlan hozzáférés hibát eredményez.

2. JSON-konfigurációs:

   • set-session-context engedélyezve van a felhasználói metaadatok továbbítása a hozzáférési jogkivonatból az adatbázisba.
   • A parameters tulajdonság leképozza a tárolt eljáráshoz szükséges userId paramétert.
   • A permissions blokk biztosítja, hogy csak hitelesített felhasználók hajthatják végre a tárolt eljárást.

Adatforrásfájlok

A Data API Builder több konfigurációs fájlt támogat a különböző adatforrásokhoz, és az egyiket a legfelső szintű fájl kezeli runtime beállításokat. Minden konfiguráció ugyanazt a sémát használja, így hiba nélkül runtime beállításokat. A gyermekkonfigurációk automatikusan egyesülnek, de kerülni kell a körkörös hivatkozásokat. Az entitások külön fájlokra oszthatók a jobb kezelés érdekében, de az entitások közötti kapcsolatoknak ugyanabban a fájlban kell lenniük.

Formátum

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

Konfigurációs fájlokkal kapcsolatos szempontok

• Minden konfigurációs fájlnak tartalmaznia kell a data-source tulajdonságot.
• Minden konfigurációs fájlnak tartalmaznia kell a entities tulajdonságot.
• A runtime beállítást csak a legfelső szintű konfigurációs fájlból használja, még akkor is, ha más fájlok is tartalmazzák.
• A gyermekkonfigurációs fájlok saját gyermekfájlokat is tartalmazhatnak.
• A konfigurációs fájlok igény szerint almappákba rendezhetők.
• Az entitásneveknek minden konfigurációs fájlban egyedinek kell lenniük.
• A különböző konfigurációs fájlok entitásai közötti kapcsolatok nem támogatottak.

Példák

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

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

Az almappák szintaxisa is támogatott:

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

Runtime

A runtime szakasz azokat a beállításokat ismerteti, amelyek befolyásolják a futtatókörnyezet működését és az összes közzétett entitás beállításait.

Formátum

{
  "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)
    }
  }
}

Kellékek

Példák

Íme egy példa egy futtatókörnyezeti szakaszra, amelynek több általános alapértelmezett paramétere van megadva.

{
  "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 (futtatókörnyezet)

Ez az objektum határozza meg, hogy a GraphQL engedélyezve van-e, és az entitás graphQL-típusként való közzétételéhez használt név[ek]. Ez az objektum nem kötelező, és csak akkor használható, ha az alapértelmezett név vagy beállítások nem elegendőek. Ez a szakasz a GraphQL-végpont globális beállításait ismerteti.

Formátum

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

Kellékek

Engedélyezve (GraphQL-futtatókörnyezet)

Meghatározza, hogy a GraphQL-végpontok globálisan engedélyezhetők vagy letilthatók-e. Ha globálisan le van tiltva, egyetlen entitás sem lenne elérhető a GraphQL-kéréseken keresztül, függetlenül az egyes entitásbeállításoktól.

Formátum

{
  "runtime": {
    "graphql": {
      "enabled": <true> (default) | <false>
    }
  }
}

Példák

Ebben a példában a GraphQL-végpont minden entitás esetében le van tiltva.

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

Mélységkorlát (GraphQL-futtatókörnyezet)

A lekérdezés maximálisan engedélyezett lekérdezési mélysége.

A GraphQL a beágyazott lekérdezések kapcsolatdefiníciókon alapuló kezelésére hihetetlen funkció, amely lehetővé teszi a felhasználók számára, hogy összetett, kapcsolódó adatokat kérjenek le egyetlen lekérdezésben. Mivel azonban a felhasználók továbbra is beágyazott lekérdezéseket adnak hozzá, a lekérdezés összetettsége nő, ami végül az adatbázis és az API-végpont teljesítményét és megbízhatóságát is veszélyeztetheti. A helyzet kezeléséhez a runtime/graphql/depth-limit tulajdonság beállítja a GraphQL-lekérdezések maximális megengedett mélységét (és mutációját). Ez a tulajdonság lehetővé teszi a fejlesztők számára, hogy egyensúlyt teremtsen, így a felhasználók élvezhetik a beágyazott lekérdezések előnyeit, miközben korlátokat szabnak a rendszer teljesítményét és minőségét veszélyeztető forgatókönyvek megelőzésére.

Példák

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

Elérési út (GraphQL-futtatókörnyezet)

Meghatározza azt az URL-útvonalat, ahol a GraphQL-végpont elérhetővé válik. Ha például ezt a paramétert /graphqlértékre állítja, a GraphQL-végpont /graphqlként jelenik meg. Alapértelmezés szerint az elérési út /graphql.

Formátum

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

Példák

Ebben a példában a GraphQL URI fő értéke /query.

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

Bevezetés engedélyezése (GraphQL-futtatókörnyezet)

Ez a logikai jelölő szabályozza, hogy a GraphQL-végponton sémabevezető lekérdezéseket hajthat végre. Az introspekció engedélyezésével az ügyfelek lekérdezhetik a sémát az elérhető adattípusokról, a végrehajtható lekérdezések típusáról és az elérhető mutációkról.

Ez a funkció a GraphQL API szerkezetének megértéséhez és a lekérdezéseket automatikusan generáló eszközökhöz használható a fejlesztés során. Éles környezetekben azonban le lehet tiltani az API sémaadatainak elrejtését és a biztonság növelését. Alapértelmezés szerint az introspection engedélyezve van, ami lehetővé teszi a GraphQL-séma azonnali és átfogó feltárását.

Formátum

{
  "runtime": {
    "graphql": {
      "allow-introspection": <true> (default) | <false>
    }
  }
}

Példák

Ebben a példában az introspection le van tiltva.

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

Több mutáció (GraphQL-futtatókörnyezet)

A GraphQL-futtatókörnyezet összes mutációs műveletét konfigurálja.

Formátum

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

Kellékek

Több mutáció – létrehozás (GraphQL-futtatókörnyezet)

Több létrehozási műveletet konfigurál a GraphQL-futtatókörnyezethez.

Formátum

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

Kellékek

Példák

Az alábbiakban bemutatjuk, hogyan engedélyezhet és használhat több mutációt a GraphQL-futtatókörnyezetben. Ebben az esetben a create művelet úgy van konfigurálva, hogy lehetővé tegye több rekord létrehozását egyetlen kérelemben a runtime.graphql.multiple-mutations.create.enabled tulajdonság truebeállításával.

Konfigurációs példa

Ez a konfiguráció több create mutációt tesz lehetővé:

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

GraphQL-mutációs példa

A fenti konfiguráció használatával a következő mutáció több User rekordot hoz létre egyetlen műveletben:

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 (futtatókörnyezet)

Ez a szakasz a REST-végpontok globális beállításait ismerteti. Ezek a beállítások alapértelmezésként szolgálnak az összes entitás esetében, de a saját konfigurációjukban entitásonként felül lehet bírálni őket.

Formátum

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

Kellékek

Engedélyezve (REST-futtatókörnyezet)

Logikai jelző, amely meghatározza a REST-végpontok globális elérhetőségét. Ha le van tiltva, az entitások nem érhetők el REST-en keresztül, függetlenül az egyes entitásbeállításoktól.

Formátum

{
  "runtime": {
    "rest": {
      "enabled": <true> (default) | <false>,
    }
  }
}

Példák

Ebben a példában a REST API-végpont minden entitás esetében le van tiltva.

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

Elérési út (REST-futtatókörnyezet)

Beállítja az url-címet az összes közzétett REST-végpont eléréséhez. Az path beállítása például /api teszi elérhetővé a REST-végpontot /api/<entity>. A mellékút nem engedélyezett. Ez a mező nem kötelező, az alapértelmezett /api.

Formátum

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

Példák

Ebben a példában a rest API URI gyökér /data.

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

Kérelem törzse – szigorú (REST-futtatókörnyezet)

Ez a beállítás azt szabályozza, hogy a REST-mutációs műveletek kérelemtörzse (például POST, PUT, PATCH) mennyire van érvényesítve.

• true (alapértelmezett): A kérelemtörzs azon mezői, amelyek nem képeznek le táblázatoszlopokat, BadRequest kivételt okoznak.
• false: A rendszer figyelmen kívül hagyja a további mezőket, és csak az érvényes oszlopokat dolgozza fel.

Ez a beállítás nem vonatkozik GET kérelmekre, mivel a kérés törzsét mindig figyelmen kívül hagyja a rendszer.

Viselkedés adott oszlopkonfigurációkkal

• Az alapértelmezett () értékkel rendelkező oszlopokat a rendszer csak akkor hagyja figyelmen kívül INSERT során, ha a hasznos adat értéke null. Az alapértelmezett() oszlopokat a rendszer nem hagyja figyelmen kívül UPDATE a hasznos adatok értékétől függetlenül.
• A számított oszlopok mindig figyelmen kívül lesznek hagyva.
• Az automatikusan létrehozott oszlopok mindig figyelmen kívül lesznek hagyva.

Formátum

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

Példák

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

Példakonfiguráció

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

Insert Behavior with request-body-strict: false

Payload-kérése:

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

eredményként kapott beszúrási utasítás:

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.

Válasz hasznos adatai:

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

FRISSÍTÉSi viselkedés request-body-strict: false

Payload-kérése:

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

eredményként kapott frissítési utasítás:

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

Válasz hasznos adatai:

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

Gazdagép (futtatókörnyezet)

A futtatókörnyezet konfigurációjának host szakasza kulcsfontosságú beállításokat biztosít a Data API builder működési környezetéhez. Ezek a beállítások tartalmazzák a működési módokat, a CORS-konfigurációt és a hitelesítési adatokat.

Formátum

{
  "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>"
        }
      }
    }
  }
}

Kellékek

Példák

Íme egy példa a fejlesztési üzemeltetésre konfigurált futtatókörnyezetre.

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

Mód (Gazdagép futtatókörnyezete)

Meghatározza, hogy a Data API builder motorjának development vagy production módban kell-e futnia. Az alapértelmezett érték: production.

A mögöttes adatbázishibák általában részletesen jelennek meg, ha a naplók alapértelmezett részletességi szintjét a fejlesztés során Debug értékre állítja. Éles környezetben a naplók részletességi szintje Error.

Formátum

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

Értékrend

Íme a tulajdonság engedélyezett értékeinek listája:

Viselkedésmódok

• Csak development módban érhető el a Swagger.
• Csak development módban érhető el a Banana Cake Pop.

Válasz maximális mérete (futtatókörnyezet)

Az adott eredmény maximális méretét (megabájtban) állítja be. Ez a beállítás lehetővé teszi a felhasználók számára, hogy konfigurálják a gazdaplatform memóriája által az alapul szolgáló adatforrásokból származó adatok streamelése során kezelhető adatok mennyiségét.

Ha a felhasználók nagy eredményhalmazokat kérnek, az megterhelheti az adatbázist és a Data API buildert. Ennek megoldásához max-response-size-mb lehetővé teszi a fejlesztők számára, hogy megabájtban mérve korlátozzák a válasz maximális méretét az adatforrásból származó adatfolyamként. Ez a korlát a teljes adatméreten alapul, nem a sorok számán. Mivel az oszlopok mérete eltérő lehet, egyes oszlopok (például szöveg, bináris, XML vagy JSON) akár 2 GB-ot is tartalmazhatnak, így az egyes sorok akár nagyon nagyok is lehetnek. Ez a beállítás segít a fejlesztőknek megvédeni végpontjaikat a válaszméretek korlátozásával és a rendszer túlterhelésének megelőzésével, miközben rugalmasan kezelik a különböző adattípusokat.

Engedélyezett értékek

Formátum

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

CORS (Gazdagép-futtatókörnyezet)

A Data API builder motor gazdagépének több forrásból származó erőforrás-megosztási (CORS- ) beállításai.

Formátum

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

Kellékek

Hitelesítő adatok engedélyezése (gazdagép-futtatókörnyezet)

Ha igaz, beállítja a Access-Control-Allow-Credentials CORS-fejlécet.

Formátum

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

Forrás (gazdagép-futtatókörnyezet)

Beállít egy tömböt a CORS engedélyezett forrásainak listájával. Ez a beállítás lehetővé teszi a * helyettesítő karaktert az összes forráshoz.

Formátum

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

Példák

Íme egy példa egy gazdagépre, amely minden forrásból származó hitelesítő adatok nélkül teszi lehetővé a CORS-t.

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

Hitelesítés (gazdagép futtatókörnyezete)

Konfigurálja a Data API Builder-gazdagép hitelesítését.

Formátum

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

Kellékek

hitelesítés és az ügyfelek feladatai

A Data API Buildert úgy tervezték, hogy szélesebb körű biztonsági folyamaton belül működjön, és a kérések feldolgozása előtt fontos lépéseket kell konfigurálnia. Fontos tisztában lenni azzal, hogy a Data API Builder nem hitelesíti a közvetlen hívót (például a webalkalmazást), hanem a végfelhasználót egy megbízható identitásszolgáltató által biztosított érvényes JWT-jogkivonat (például Entra-azonosító) alapján. Amikor egy kérés eléri a Data API Buildert, feltételezi, hogy a JWT-jogkivonat érvényes, és ellenőrzi a konfigurált előfeltételeket, például konkrét jogcímeket. Ezután engedélyezési szabályokat alkalmazunk annak meghatározására, hogy a felhasználó mit érhet el vagy módosíthat.

Az engedélyezést követően a Data API Builder a kapcsolati sztringben megadott fiókkal hajtja végre a kérést. Mivel ez a fiók gyakran emelt szintű engedélyeket igényel a különböző felhasználói kérések kezeléséhez, a kockázat csökkentése érdekében elengedhetetlen a hozzáférési jogosultságok minimalizálása. Javasoljuk az architektúra védelmét úgy, hogy konfigurál egy privát kapcsolatot az előtérbeli webalkalmazás és az API-végpont között, valamint a Data API Buildert üzemeltető gép megkeményedésével. Ezek a mértékek biztosítják a környezet biztonságát, védik az adatokat, és minimalizálják azokat a biztonsági réseket, amelyeket a bizalmas információk elérésére, módosítására vagy kiszűrésére lehet kihasználni.

Szolgáltató (gazdagép futtatókörnyezete)

A authentication.provider konfiguráción belüli host beállítás határozza meg a Data API builder által használt hitelesítési módszert. Meghatározza, hogy az API hogyan ellenőrzi az erőforrásokhoz hozzáférni próbáló felhasználók vagy szolgáltatások identitását. Ez a beállítás rugalmas üzembe helyezést és integrációt tesz lehetővé a különböző környezetekhez és biztonsági követelményekhez igazított különböző hitelesítési mechanizmusok támogatásával.

Formátum

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

Értékrend

Íme a tulajdonság engedélyezett értékeinek listája:

JSON webes jogkivonatok (gazdagép-futtatókörnyezet)

Ha a hitelesítésszolgáltató AzureAD (Microsoft Entra ID) értékre van állítva, akkor ez a szakasz a JSOn Webes jogkivonatok (JWT) jogkivonat célközönségének és kiállítóinak megadásához szükséges. Ezekkel az adatokkal érvényesítheti a jogkivonatokat a Microsoft Entra-bérlőn.

Akkor szükséges, ha a hitelesítésszolgáltató AzureAD a Microsoft Entra-azonosítóhoz. Ebben a szakaszban meg kell adni a audience és a issuer, hogy a kapott JWT-jogkivonatot a kívánt AzureAD-bérlőn érvényesítse hitelesítés céljából.

Formátum

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

Kellékek

Példák

A Data API Builder (DAB) rugalmas hitelesítési támogatást nyújt a Microsoft Entra Identity és az egyéni JSON Web Token (JWT) kiszolgálók integrálásával. Ezen a képen a JWT Server azt a hitelesítési szolgáltatást jelöli, amely JWT-jogkivonatokat ad ki az ügyfeleknek a sikeres bejelentkezéskor. Az ügyfél ezután átadja a jogkivonatot a DAB-nak, amely kikérdezheti a jogcímeit és tulajdonságait.

Az alábbiakban példákat láthat a host tulajdonságra, amelyek különböző architekturális döntéseket hozhatnak a megoldásban.

Azure Static Web Apps

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

A StaticWebAppsa Data API Builder elvárja, hogy az Azure Static Web Apps hitelesítse a kérést, és a X-MS-CLIENT-PRINCIPAL HTTP-fejléc jelen van.

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

A hitelesítés egy támogatott identitásszolgáltatóhoz van delegálva, ahol a hozzáférési jogkivonat kibocsátható. A Data API Builder felé irányuló bejövő kérésekhez egy beszerzett hozzáférési jogkivonatot kell tartalmaznia. A Data API Builder ezután ellenőrzi a bemutatott hozzáférési jogkivonatokat, biztosítva, hogy a Data API Builder legyen a jogkivonat célközönsége.

Microsoft Entra-azonosító

{
 "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"
   }
  }
 }
}

Szimulátor (csak fejlesztés)

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

Célközönség (gazdagép-futtatókörnyezet)

A JWT-jogkivonat célközönsége.

Formátum

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

Kiállító (gazdagép futtatókörnyezete)

A JWT-jogkivonat kiállítója.

Formátum

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

Lapozás (futtatókörnyezet)

A REST- és GraphQL-végpontok lapozási korlátait konfigurálja.

Formátum

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

Kellékek

Példakonfiguráció

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

REST-lapozási példa

Ebben a példában a REST GET kérés kiadása https://localhost:5001/api/users két rekordot ad vissza a value tömbben, mert a default-page-size értéke 2. Ha további eredmények is léteznek, a Data API Builder egy nextLink tartalmaz a válaszban. A nextLink egy $after paramétert tartalmaz a következő adatoldal beolvasásához.

Kérés:

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

Válasz:

{
  "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=="
}

A nextLinkhasználatával az ügyfél lekérheti a következő találatokat.

GraphQL-lapozási példa

A GraphQL-ben a lapozáshoz használja a hasNextPage és endCursor mezőket. Ezek a mezők azt jelzik, hogy további eredmények érhetők-e el, és a kurzort adja meg a következő oldal beolvasásához.

Lekérdezés:

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

Válasz:

{
  "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=="
    }
  }
}

A következő lap beolvasásához adja meg a endCursor értéket a következő lekérdezésben:

Lekérdezés kurzorral:

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

Oldalméret módosítása

A REST és a GraphQL egyaránt lehetővé teszi a lekérdezésenkénti eredmények számának módosítását $limit (REST) vagy first (GraphQL) használatával.

Példa REST-lekérdezésre:

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

Példa GraphQL-lekérdezésre:

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

Oldalméret maximális száma (lapszámozási futtatókörnyezet)

Beállítja a REST vagy a GraphQL által visszaadott legfelső szintű rekordok maximális számát. Ha egy felhasználó több kérést kér, mint max-page-size, az eredmények a max-page-sizelesznek leképezve.

Engedélyezett értékek

Formátum

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

Alapértelmezett oldalméret (lapszámozási futtatókörnyezet)

Beállítja a lapozás engedélyezésekor visszaadott legfelső szintű rekordok alapértelmezett számát, de nincs megadva explicit oldalméret.

Engedélyezett értékek

Gyorsítótár (futtatókörnyezet)

Engedélyezi és konfigurálja a teljes futtatókörnyezet gyorsítótárazását.

Formátum

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

Kellékek

Példák

Ebben a példában a gyorsítótár engedélyezve van, és az elemek 30 másodperc után lejárnak.

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

Engedélyezve (Gyorsítótár-futtatókörnyezet)

Globális gyorsítótárazást tesz lehetővé az összes entitás számára. Alapértelmezett érték: false.

Formátum

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

Példák

Ebben a példában a gyorsítótár le van tiltva.

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

TTL másodpercben (gyorsítótár-futtatókörnyezet)

Az élettartam (TTL) értékét másodpercben konfigurálja a gyorsítótárazott elemekhez. Ennyi idő elteltével a rendszer automatikusan eltávolítja az elemeket a gyorsítótárból. Az alapértelmezett érték 5 másodperc.

Formátum

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

Példák

Ebben a példában a gyorsítótár globálisan engedélyezve van, és minden elem 15 másodperc után lejár.

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

Telemetria (futtatókörnyezet)

Ez a tulajdonság konfigurálja az Application Insightst az API-naplók központosítására. További információ.

Formátum

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

Application Insights (Telemetria-futtatókörnyezet)

Engedélyezve (Application Insights-telemetria)

Kapcsolati sztring (Application Insights-telemetria)

Entitások

A entities szakasz a konfigurációs fájl magjaként szolgál, így hidat hoz létre az adatbázis-objektumok és a hozzájuk tartozó API-végpontok között. Ez a szakasz leképzi az adatbázis-objektumokat a közzétett végpontokra. Ez a szakasz a tulajdonságok leképezését és az engedélydefiníciót is tartalmazza. Minden közzétett entitás egy dedikált objektumban van definiálva. A rendszer az objektum tulajdonságnevét használja a közzéteendő entitás neveként.

Ez a szakasz azt határozza meg, hogy az adatbázis egyes entitásai hogyan jelenik meg az API-ban, beleértve a tulajdonságleképezéseket és az engedélyeket. Minden entitás a saját alszakaszában van beágyazva, és az entitás neve kulcsként szolgál a konfiguráció során.

Formátum

{
  "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>
          }
        }
      ]
    }
  }
}

Kellékek

Példák

Ez a JSON-objektum például arra utasítja a Data API Buildert, hogy tegyen közzé egy User nevű GraphQL-entitást és egy REST-végpontot, amely a /User útvonalon keresztül érhető el. A dbo.User adatbázistábla az entitást háttérbe irányítja, és a konfiguráció lehetővé teszi, hogy bárki névtelenül hozzáférjen a végponthoz.

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

Ez a példa deklarálja a User entitást. Ez a név User a konfigurációs fájl bármely pontján használható, ahol entitásokra hivatkoznak. Ellenkező esetben az entitás neve nem releváns a végpontok szempontjából.

{
  "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'"
          }
        }
      ]
    }
  }
}

Forrás

A {entity}.source konfiguráció összekapcsolja az API által közzétett entitást és annak mögöttes adatbázis-objektumát. Ez a tulajdonság megadja az entitás által képviselt adatbázistáblát, nézetet vagy tárolt eljárást, amely közvetlen kapcsolatot hoz létre az adatok lekéréséhez és kezeléséhez.

Olyan egyszerű forgatókönyvek esetén, amikor az entitás közvetlenül egy adatbázistáblára van leképezve, a forrástulajdonságnak csak az adatbázis-objektum nevére van szüksége. Ez az egyszerűség megkönnyíti a gyakori használati esetek gyors beállítását: "source": "dbo.User".

Formátum

{
  "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>
        }
      }
    }
  }
}

Kellékek

Példák

1. Egyszerű táblázatleképezés:

Ez a példa bemutatja, hogyan társíthat egy User entitást egy forrástáblához dbo.Users.

SQL-

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

konfigurációs

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

2. Tárolt eljárás példa:

Ez a példa bemutatja, hogyan társíthat egy User entitást egy forrásalkalmazáshoz dbo.GetUsers.

SQL-

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

konfigurációs

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

A mappings tulajdonság nem kötelező a tárolt eljárásokhoz.

Tárgy

A használni kívánt adatbázis-objektum neve. Ha az objektum a dbo sémához tartozik, a séma megadása nem kötelező. Emellett az objektumnevek körüli szögletes zárójelek (például [dbo].[Users] és dbo.Users) használhatók vagy kihagyhatók.

Példák

SQL-

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

konfigurációs

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

Alternatív jelölés séma és zárójelek nélkül:

Ha a táblázat a dbo sémában található, kihagyhatja a sémát vagy a zárójeleket:

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

Típus (entitások)

A type tulajdonság azonosítja az entitás mögötti adatbázis-objektum típusát, beleértve a view, tableés stored-procedure. Ez a tulajdonság kötelező, és nincs alapértelmezett értéke.

Formátum

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

Értékrend

Példák

1. Példa táblázatra:

SQL-

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

konfigurációs

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

2. Példa megtekintése:

SQL-

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

konfigurációs

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

Megjegyzés: A key-fields megadása azért fontos a nézeteknél, mert nincsenek bennük eredendő elsődleges kulcsok.

3. Tárolt eljárás példa:

SQL-

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

konfigurációs

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

Kulcsmezők

A {entity}.key-fields tulajdonság különösen szükséges a nézetek által támogatott entitásokhoz, így a Data API Builder tudja, hogyan azonosíthat és adhat vissza egyetlen elemet. Ha typekey-fieldsmegadása nélkül view, a motor nem indul el. Ez a tulajdonság táblákkal és tárolt eljárásokkal engedélyezett, de ezekben az esetekben nem használatos.

Formátum

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

Példa: Nézet kulcsmezőkkel

Ez a példa a dbo.AdminUsers nézetet használja a kulcsmezőként megjelölt Id.

SQL-

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

konfigurációs

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

Paraméterek

A entities.{entity}.sourceparameters tulajdonsága tárolt eljárások által támogatott entitásokhoz használható. Biztosítja a tárolt eljáráshoz szükséges paraméternevek és adattípusok megfelelő leképezését.

Formátum

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

1. példa: Tárolt eljárás paraméterek nélkül

SQL-

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

konfigurációs

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

2. példa: Tárolt eljárás paraméterekkel

SQL-

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

konfigurációs

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

Engedélyek

Ez a szakasz azt határozza meg, hogy ki férhet hozzá a kapcsolódó entitáshoz, és hogy milyen műveletek engedélyezettek. Az engedélyek szerepkörök és CRUD-műveletek: create, read, updateés delete. A permissions szakasz meghatározza, hogy mely szerepkörök férhetnek hozzá a kapcsolódó entitáshoz, és mely műveleteket használhatják.

Formátum

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

Példák

1. példa: Névtelen szerepkör a felhasználói entitásokon

Ebben a példában a anonymous szerepkör az User entitás összes lehetséges műveletéhez való hozzáféréssel van definiálva.

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

2. példa: Vegyes műveletek névtelen szerepkörökhöz

Ez a példa bemutatja, hogyan keverheti össze a sztring- és objektumtömbműveleteket az User entitáshoz.

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

Névtelen szerepkör: Lehetővé teszi a névtelen felhasználók számára, hogy az összes mezőt beolvassák, kivéve egy feltételezett bizalmas mezőt (például secret-field). A "include": ["*"]"exclude": ["secret-field"] használatával elrejti a secret-field, miközben minden más mezőhöz hozzáférést engedélyez.

Hitelesített szerepkör: Lehetővé teszi a hitelesített felhasználók számára adott mezők olvasását és frissítését. Például a id, nameés age explicit belefoglalása, de a isAdmin kizárása bemutatja, hogy a kizárások hogyan bírálják felül a belefoglalásokat.

rendszergazdai szerepkör: A rendszergazdák kivétel nélkül minden műveletet (*) végrehajthatnak az összes mezőn. Ha üres "exclude": [] tömböt tartalmazó "include": ["*"] ad meg, az minden mezőhöz hozzáférést biztosít.

Ez a konfiguráció:

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

gyakorlatilag megegyezik a következő értékeket:

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

Vegye figyelembe ezt a beállítást is:

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

Ez azt határozza meg, hogy a mezők nincsenek explicit módon belefoglalva, és az összes mező ki van zárva, ami általában teljes mértékben korlátozza a hozzáférést.

Gyakorlati használat: Az ilyen konfiguráció ellentétesnek tűnhet, mivel minden mezőhöz korlátozza a hozzáférést. Azonban olyan helyzetekben is használható, amikor egy szerepkör bizonyos műveleteket hajt végre (például entitásokat hoz létre), és nem fér hozzá az adataihoz.

Ugyanez a viselkedés, de különböző szintaxissal a következő lenne:

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

Ez a beállítás csak Id és Name mezőket próbál belefoglalni, de kizárja az összes mezőt a excludehelyettesítő karaktere miatt.

Ugyanezt a logikát a következő módon lehet kifejezni:

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

Mivel exclude elsőbbséget élvez include, a exclude: ["*"] megadása azt jelenti, hogy az összes mező ki van zárva, még a includemezői is. Így első pillantásra úgy tűnhet, hogy ez a konfiguráció megakadályozza a mezők akadálymentesítését.

Fordított: Ha a szándék az, hogy csak Id és Name mezőkhöz adjon hozzáférést, egyértelműbb és megbízhatóbb, ha csak azokat a mezőket adja meg a include szakaszban kizárási helyettesítő karakter használata nélkül:

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

Kellékek

Szerep

Annak a szerepkörnek a nevét tartalmazó sztring, amelyre a megadott engedély vonatkozik. A szerepkörök beállítják azt az engedélykörnyezetet, amelyben a kérést végre kell hajtani. A futtatókörnyezeti konfigurációban definiált összes entitáshoz meghatározhat szerepköröket és kapcsolódó engedélyeket, amelyek meghatározzák, hogyan érhető el az entitás REST- és GraphQL-végpontokon keresztül. A szerepkörök nem additívak.

A Data API Builder egyetlen szerepkör kontextusában értékeli ki a kéréseket:

Formátum

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

Példák

Ez a példa egy reader nevű szerepkört határoz meg, amely csak read engedélyekkel rendelkezik a User entitáson.

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

A <custom-role> akkor használhatja, ha egy érvényes hozzáférési jogkivonat jelenik meg , és a X-MS-API-ROLE HTTP-fejlécet, megadva egy felhasználói szerepkört, amely a hozzáférési jogkivonat szerepkör-jogcímében is szerepel. Az alábbiakban példákat talál az User entitáshoz érkező GET-kérelmekre, beleértve az engedélyezési tulajdonosi jogkivonatot és a X-MS-API-ROLE fejlécet is a REST végpontbázison, /apilocalhost különböző nyelveket használva.

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

Műveletek (sztringtömb)

Sztringértékek tömbje, amely részletezi, hogy milyen műveletek engedélyezettek a társított szerepkörhöz. table és view adatbázis-objektumok esetében a szerepkörök a create, read, updatevagy delete műveletek bármilyen kombinációját használhatják. Tárolt eljárások esetén a szerepkörök csak a execute műveletet hajthatják végre.

Példák

Ez a példa create és read engedélyeket ad egy contributor nevű szerepkörhöz, és delete engedélyeket a User entitáson auditor nevű szerepkörhöz.

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

Egy másik példa:

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

Műveletek (objektumtömb)

A társított szerepkör engedélyezett műveleteit részletező műveleti objektumok tömbje. table és view objektumok esetében a szerepkörök a create, read, updatevagy deletebármilyen kombinációját használhatják. Tárolt eljárások esetén csak execute engedélyezett.

Formátum

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

Kellékek

Példa

Ez a példa csak read engedélyt ad a User entitás auditor szerepkörére mező- és szabályzatkorlátozásokkal.

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

Akció

Megadja az adatbázis-objektumon engedélyezett konkrét műveletet.

Értékrend

Formátum

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

Példa

Íme egy példa, amelyben anonymous felhasználók execute egy tárolt eljárást, és read a User táblából.

{
  "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"
            }
          ]
        }
      ]
    }
  }
}

Mezők

Részletes specifikációk, amelyeken adott mezők engedélyezettek az adatbázis-objektumhoz való hozzáféréshez. A szerepkör-konfiguráció egy olyan objektumtípus, amely két belső tulajdonsággal rendelkezik, include és exclude. Ezek az értékek támogatják a fieldsszakaszban engedélyezett adatbázisoszlopok (mezők) részletes meghatározását.

Formátum

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

Példák

Ebben a példában a anonymous szerepkör az idkivételével minden mezőből beolvasható, de az elemek létrehozásakor az összes mezőt használhatja.

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

A közös munka belefoglalása és kizárása. A * szakaszban szereplő helyettesítő karakter include az összes mezőt jelzi. A exclude szakaszban feljegyzett mezők elsőbbséget élveznek a include szakaszban feljegyzett mezőkkel szemben. A definíció lefordítja tartalmazza az összes mezőt, kivéve a "last_updated" mezőt.

"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

A policydefiniált action szakasz olyan elemszintű biztonsági szabályokat (adatbázis-szabályzatokat) határoz meg, amelyek korlátozzák a kérésből visszaadott eredményeket. Az alszakasz database a kérések végrehajtása során kiértékelt adatbázis-szabályzatkifejezést jelöli.

Formátum

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

Kellékek

Leírás

A database szabályzat: az adatbázis kiértékelését egy lekérdezésre lefordított OData-szerű kifejezés, beleértve az eq, ltés gtoperátorokat is. Ahhoz, hogy egy kérelem eredményei vissza legyenek adva, a kérelem adatbázis-szabályzatból feloldott lekérdezési predikátumának true kell kiértékelnie az adatbázison való végrehajtás során.

A predicate egy IGAZ vagy HAMIS értékre kiértékelt kifejezés. A predikátumok az WHERE záradékok és HAVING záradékok keresési feltételeiben, a FROM záradékok illesztési feltételeiben és egyéb olyan szerkezetekben használatosak, ahol logikai értékre van szükség. (Microsoft Learn Docs)

Adatbázis-szabályzat

Adatbázisházirend-kifejezés létrehozásakor kétféle irányelv használható az adatbázis-szabályzatok kezelésére:

Íme néhány példa adatbázis-szabályzatra:

• @claims.userId eq @item.OwnerId
• @claims.userId gt @item.OwnerId
• @claims.userId lt @item.OwnerId

A Data API Builder összehasonlítja a UserId jogcím értékét az adatbázismező OwnerIdértékével. Az eredmény hasznos adatai csak olyan rekordokat tartalmaznak, amelyek megfelelnek a kérés metaadatainak és az adatbázisházirend-kifejezésnek.

Korlátozások

Az adatbázis-szabályzatok táblákhoz és nézetekhez támogatottak. A tárolt eljárások nem konfigurálhatók szabályzatokkal.

Az adatbázis-szabályzatok nem akadályozzák meg a kérések végrehajtását az adatbázisban. Ennek a viselkedésnek az az oka, hogy az adatbázismotornak átadott generált lekérdezések predikátumaként vannak feloldva.

Az adatbázis-szabályzatok csak a actionslétrehozási, olvasási, frissítésiés törlésitámogatottak. Mivel a tárolt eljáráshívásokban nincs predikátum, nem fűzhetők hozzá.

Támogatott OData-szerű operátorok

További információ: bináris operátorok.

További információ: nem naplós operátorok.

Entitásmezőnév korlátozásai

• szabályok: Betűvel vagy aláhúzásjellel (_) kell kezdődnie, amelyet legfeljebb 127 betű, aláhúzásjel (_) vagy számjegy (0-9) követ.
• Hatás: Az ezekhez a szabályokhoz nem igazodó mezők nem használhatók közvetlenül az adatbázis-szabályzatokban.
• Megoldás: A mappings szakasz használatával aliasokat hozhat létre olyan mezőkhöz, amelyek nem felelnek meg ezeknek az elnevezési konvencióknak; a leképezések biztosítják, hogy az összes mező szerepelhessen a szabályzatkifejezésekben.

mappings használata nem konformáló mezőkhöz

Ha az entitásmezők nevei nem felelnek meg az OData szintaxis szabályainak, vagy egyszerűen csak más okokból szeretné aliasolni őket, a konfiguráció mappings szakaszában definiálhat aliasokat.

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

Ebben a példában field-1-name az eredeti adatbázismező neve, amely nem felel meg az OData elnevezési konvencióinak. Ha field-1-name és field-1-alias térképet hoz létre, az adatbázis-szabályzatkifejezésekben problémamentesen hivatkozhat erre a mezőre. Ez a megközelítés nem csak az OData elnevezési konvenciók betartásában segít, hanem javítja az adatmodell érthetőségét és akadálymentességét a GraphQL- és RESTful-végpontokon is.

Példák

Vegyünk egy Employee nevű entitást egy Olyan Data API-konfigurációban, amely jogcím- és elemirányelveket is használ. Biztosítja, hogy az adathozzáférés biztonságosan kezelhető legyen a felhasználói szerepkörök és az entitások tulajdonjoga alapján:

{
  "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"
      }
    }
  }
}

Entitásdefiníciós: A Employee entitás REST- és GraphQL-felületekhez van konfigurálva, ami azt jelzi, hogy az adatok lekérdezhetők vagy módosíthatók ezeken a végpontokon keresztül.

forráskonfigurációs: Az adatbázis HRUNITS azonosítja, kulcsmezőként pedig employee NUM.

leképezések: Az aliasok employee NUM, employee Nameés department COIDEmployeeId, EmployeeNameés DepartmentIdleképezésére szolgálnak, leegyszerűsítve a mezőneveket, és esetleg elrejtik a bizalmas adatbázisséma részleteit.

házirendalkalmazás: A policy szakasz OData-szerű kifejezéssel alkalmaz adatbázis-szabályzatot. Ez a szabályzat korlátozza az adathozzáférést a HR-szerepkörrel (@claims.role eq 'HR') rendelkező felhasználóknak, illetve azoknak a felhasználóknak, akiknek UserId jogcíme megegyezik EmployeeId – a mező aliasa – az adatbázisban (@claims.userId eq @item.EmployeeId). Biztosítja, hogy az alkalmazottak csak akkor férhessenek hozzá a saját rekordjaikhoz, ha a HR-részleghez tartoznak. A szabályzatok dinamikus feltételek alapján kényszeríthetik ki a sorszintű biztonságot.

Adatbázis

A policydefiniált action szakasz olyan elemszintű biztonsági szabályokat (adatbázis-szabályzatokat) határoz meg, amelyek korlátozzák a kérésből visszaadott eredményeket. Az alszakasz database a kérések végrehajtása során kiértékelt adatbázis-szabályzatkifejezést jelöli.

Formátum

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

Ez a tulajdonság azt az adatbázisházirend-kifejezést jelöli, amelyet a kérelem végrehajtása során kiértékelnek. A szabályzatsztring egy OData-kifejezés, amely az adatbázis által kiértékelt lekérdezésre lesz lefordítva. A @item.OwnerId eq 2000 szabályzatkifejezés például a lekérdezési predikátumra WHERE <schema>.<object-name>.OwnerId = 2000lesz lefordítva.

Ahhoz, hogy egy kérelem eredményei vissza legyenek adva, a kérelem adatbázis-szabályzatból feloldott lekérdezési predikátumának true kell kiértékelnie az adatbázison való végrehajtás során.

Adatbázisházirend-kifejezés létrehozásakor kétféle irányelv használható az adatbázis-szabályzat kezelésére:

Példák

Egy alapszintű szabályzatkifejezés például kiértékelheti, hogy egy adott mező igaz-e a táblában. Ez a példa kiértékeli, hogy a soft_delete mező false-e.

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

A predikátumok claims és item irányelvtípusokat is kiértékelhetnek. Ez a példa lekéri a UserId mezőt a hozzáférési jogkivonatból, és összehasonlítja azt a céladatbázistábla owner_id mezőjével.

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

Korlátozások

• Az adatbázis-szabályzatok táblákhoz és nézetekhez támogatottak. A tárolt eljárások nem konfigurálhatók szabályzatokkal.
• Az adatbázis-házirendek nem használhatók a kérések adatbázison belüli végrehajtásának megakadályozására. Ennek a korlátozásnak az az oka, hogy az adatbázis-szabályzatok lekérdezési predikátumként vannak feloldva a létrehozott adatbázis-lekérdezésekben. Az adatbázismotor végül kiértékeli ezeket a lekérdezéseket.
• Az adatbázis-szabályzatok csak a actionscreate, read, updateés deleteesetében támogatottak.
• Az adatbázisházirend OData-kifejezésszintaxisa csak ezeket a forgatókönyveket támogatja.
  • Bináris operátorok, beleértve, de nem kizárólagosan; and, or, eq, gtés lt. További információ: BinaryOperatorKind.
  • Unary operátorok, például a - (negate) és not operátorok. További információ: UnaryOperatorKind.
• Az adatbázis-szabályzatok a mezőnevekre vonatkozó korlátozásokkal is rendelkeznek.
  • Betűvel vagy aláhúzásjellel kezdődő entitásmezőnevek, amelyeket legfeljebb 127 betű, aláhúzásjel vagy számjegy követ.
  • Ez a követelmény OData-specifikációnként van megadva. További információ: OData Common Schema Definition Language.

GraphQL (entitások)

Ez az objektum határozza meg, hogy a GraphQL engedélyezve van-e, és az entitás graphQL-típusként való közzétételéhez használt név[ek]. Ez az objektum nem kötelező, és csak akkor használható, ha az alapértelmezett név vagy beállítások nem elegendőek.

Ez a szegmens egy entitás GraphQL-sémába való integrálását biztosítja. Lehetővé teszi a fejlesztők számára az entitás alapértelmezett értékeinek megadását vagy módosítását a GraphQL-ben. Ez a beállítás biztosítja, hogy a séma pontosan tükrözze a kívánt struktúrát és elnevezési konvenciókat.

Formátum

{
  "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"
      }
    }
  }
}

Kellékek

Példák

Ez a két példa funkcionálisan egyenértékű.

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

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

Ebben a példában a definiált entitás Book, ami azt jelzi, hogy az adatbázisban lévő könyvekhez kapcsolódó adatok készletével foglalkozunk. A GraphQL-szegmensen belüli Book entitás konfigurációja egyértelmű struktúrát kínál arra vonatkozóan, hogy hogyan kell ábrázolni és használni egy GraphQL-sémában.

Engedélyezett tulajdonság: A Book entitás a GraphQL ("enabled": true) használatával érhető el, ami azt jelenti, hogy a fejlesztők és a felhasználók GraphQL-műveleteken keresztül kérdezhetik le vagy mutálhatják a könyvadatokat.

Típus tulajdonság: Az entitás a GraphQL-sémában az egyedi névvel "Book" és a többes számmal "Books". Ez a megkülönböztetés biztosítja, hogy egyetlen könyv vagy több könyv lekérdezésekor a séma intuitívan elnevezett típusokat (Book egyetlen bejegyzéshez, Books egy listához) kínáljon, növelve az API használhatóságát.

művelettulajdonság: A művelet "query"értékre van állítva, ami azt jelzi, hogy az Book entitással a GraphQL-n keresztüli elsődleges interakció célja az adatok lekérdezése (lekérése) ahelyett, hogy mutációt (létrehozást, frissítést vagy törlést) okoz. Ez a beállítás igazodik a tipikus használati mintákhoz, ahol a könyvadatokat gyakrabban olvassák, mint módosítják.

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

Típus (GraphQL-entitás)

Ez a tulajdonság határozza meg a GraphQL-sémán belüli entitások elnevezési konvencióját. Skaláris sztringértékeket és objektumtípusokat egyaránt támogat. Az objektumérték a többes és a többes számú űrlapot adja meg. Ez a tulajdonság részletes vezérlést biztosít a séma olvashatósága és felhasználói élménye felett.

Formátum

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

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

Kellékek

Példák

A GraphQL-típus még nagyobb mértékű szabályozásához konfigurálhatja, hogy az egyes és többes számú név egymástól függetlenül legyen ábrázolva.

Ha plural hiányzik vagy hiányzik (például skaláris érték), a Data API Builder megpróbálja automatikusan pluralizálni a nevet a pluralizálás angol szabályainak megfelelően (például: https://engdic.org/singular-and-plural-noun-rules-definitions-examples)

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

Az egyéni entitásnév a sztringértékkel rendelkező type paraméterrel adható meg. Ebben a példában a motor automatikusan különbséget tesz a név egyes és többes változatai között a pluralizálás általános angol szabályainak használatával.

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

Ha explicit módon adja meg a neveket, használja a type.singular és type.plural tulajdonságokat. Ez a példa mindkét nevet explicit módon állítja be.

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

Mindkét példa funkcionálisan egyenértékű. Mindkettő ugyanazt a JSON-kimenetet adja vissza egy GraphQL-lekérdezéshez, amely a bookauthors entitásnevet használja.

{
  bookauthors {
    items {
      first_name
      last_name
    }
  }
}

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

Művelet (GraphQL-entitás)

A tárolt eljárásokra leképezett entitások esetében a operation tulajdonság a GraphQL művelettípust (lekérdezést vagy mutációt) jelöli meg, ahol a tárolt eljárás elérhető. Ez a beállítás lehetővé teszi a séma logikai rendszerezését és a GraphQL ajánlott eljárásainak betartását a funkciók befolyásolása nélkül.

Ha hiányzik, a operation alapértelmezett értéke mutation.

Formátum

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

Értékrend

Íme a tulajdonság engedélyezett értékeinek listája:

Példák

Ha operationmutation, a GraphQL-séma a következőhöz hasonló:

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

Ha operationquery, a GraphQL-séma a következőhöz hasonló:

A GraphQL-séma a következőhöz hasonló:

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

Engedélyezve (GraphQL-entitás)

Engedélyezi vagy letiltja a GraphQL-végpontot. Azt szabályozza, hogy egy entitás elérhető-e GraphQL-végpontokon keresztül. A enabled tulajdonság egyesítése lehetővé teszi, hogy a fejlesztők szelektíven tegyenek közzé entitásokat a GraphQL-sémából.

Formátum

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

REST (entitások)

A konfigurációs fájl rest szakasza az egyes adatbázis-entitások RESTful végpontjainak finomhangolására szolgál. Ez a testreszabási funkció biztosítja, hogy a közzétett REST API megfeleljen az adott követelményeknek, és javítsa a segédprogramot és az integrációs képességeket is. Elhárítja az alapértelmezett következtetési beállítások és a kívánt végpont viselkedése közötti lehetséges eltéréseket.

Formátum

{
  "entities": {
    "<entity-name>": {
      "rest": {
        "enabled": <true> (default) | <false>,
        "path": <string; default: "<entity-name>">,
        "methods": <array of strings; default: ["GET", "POST"]>
      }
    }
  }
}

Kellékek

Példák

Ez a két példa funkcionálisan egyenértékű.

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

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

Íme egy másik példa egy entitás REST-konfigurációjára.

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

Engedélyezve (REST-entitás)

Ez a tulajdonság kapcsolóként szolgál az entitások REST API-beli láthatóságához. Ha a enabled tulajdonságot true vagy falseértékre állítja, a fejlesztők szabályozhatják az adott entitásokhoz való hozzáférést, így az alkalmazásbiztonsági és funkcionalitási követelményeknek megfelelő, testre szabott API-felület érhető el.

Formátum

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

Elérési út (REST-entitás)

A path tulajdonság határozza meg azt az URI-szegmenst, amellyel egy entitást a REST API-val érhet el. Ez a testreszabás lehetővé teszi az alapértelmezett entitásnéven túli leíróbb vagy egyszerűsített végpontútvonalak használatát, ami növeli az API navigálását és az ügyféloldali integrációt. Alapértelmezés szerint az elérési út /<entity-name>.

Formátum

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

Példák

Ez a példa a Author entitást teszi elérhetővé a /auth végpont használatával.

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

Metódusok (REST-entitás)

A kifejezetten tárolt eljárásokra alkalmazható methods tulajdonság határozza meg, hogy az eljárás mely HTTP-parancsokra (például GET, POST) tud válaszolni. A metódusok lehetővé teszik a tárolt eljárások REST API-val való megjelenítésének pontos ellenőrzését, így biztosítva a RESTful szabványokkal és az ügyfél elvárásaival való kompatibilitást. Ez a szakasz aláhúzza a platform rugalmasságra és fejlesztői vezérlésre vonatkozó elkötelezettségét, amely lehetővé teszi az egyes alkalmazások egyedi igényeire szabott, pontos és intuitív API-kialakítást.

Ha nincs megadva vagy hiányzik, a methods alapértelmezett értéke POST.

Formátum

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

Értékrend

Íme a tulajdonság engedélyezett értékeinek listája:

Példák

Ez a példa arra utasítja a motort, hogy a stp_get_bestselling_authors tárolt eljárás csak HTTP GET műveleteket támogat.

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

Leképezések (entitások)

A mappings szakasz lehetővé teszi az aliasok vagy a közzétett nevek konfigurálását az adatbázis-objektummezőkhöz. A konfigurált közzétett nevek a GraphQL- és REST-végpontokra is érvényesek.

Formátum

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

Példák

Ebben a példában az adatbázis-objektum sku_title mezője dbo.magazines a titlenéven jelenik meg. Hasonlóképpen, a sku_status mező status jelenik meg a REST és a GraphQL végpontokban is.

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

Íme egy másik példa a leképezésekre.

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

leképezések: A mappings objektum a külsőleg használt intuitívabb vagy szabványosabb nevekhez (BookID, BookTitle, AuthorName) kapcsolja össze az adatbázismezőket (id, title, author). Ez az aliasolás több célt is szolgál:

• egyértelműség és konzisztencia: Lehetővé teszi a tiszta és konzisztens elnevezés használatát az API-ban, az alapul szolgáló adatbázissémától függetlenül. Az adatbázis BookID például id ként jelenik meg az API-ban, így intuitívabb a végponttal kommunikáló fejlesztők számára.

• GraphQL-megfelelőség: Az aliasmezőnevek mechanizmusának biztosításával biztosítja, hogy a GraphQL-felületen közzétett nevek megfeleljenek a GraphQL elnevezési követelményeinek. A nevekre való figyelem azért fontos, mert a GraphQL szigorú szabályokkal rendelkezik a nevekre vonatkozóan (például szóközök nélkül, betűvel vagy aláhúzásjellel kell kezdődnie stb.). Ha például egy adatbázismező neve nem felel meg ezeknek a feltételeknek, akkor megfeleltetésekkel aliasolható egy megfelelő névhez.

• rugalmassági: Ez az aliasolás absztrakciós réteget ad hozzá az adatbázisséma és az API között, lehetővé téve az egyik módosítását anélkül, hogy a másikban módosításokat igényelne. Az adatbázis mezőnevének módosítása például nem igényel frissítést az API dokumentációjában vagy az ügyféloldali kódban, ha a leképezés konzisztens marad.

• mezőnév-elfedés: A leképezés lehetővé teszi a mezőnevek elhomályosítását, ami megakadályozhatja, hogy a jogosulatlan felhasználók bizalmas információkat vonnak le az adatbázis sémájáról vagy a tárolt adatok természetéről.

• Védett adatok védelme: A mezők átnevezésével védett neveket vagy üzleti logikát is védhet, amelyekre az adatbázis eredeti mezőnevei utalhatnak.

Kapcsolatok (entitások)

Ez a szakasztérképek olyan kapcsolatdefiníciókat tartalmaznak, amelyek leképezik, hogyan kapcsolódnak az entitások más közzétett entitásokhoz. Ezek a kapcsolatdefiníciók opcionálisan részleteket is tartalmazhatnak a kapcsolatok támogatásához és érvényesítéséhez használt mögöttes adatbázis-objektumokról. Az ebben a szakaszban definiált objektumok GraphQL-mezőkként jelennek meg a kapcsolódó entitásban. További információ: Data API Builder-kapcsolatok részletezése.

A relationships szakasz ismerteti, hogyan működnek együtt az entitások a Data API builderben, részletezve az ilyen kapcsolatok társításait és lehetséges adatbázis-támogatását. Az egyes kapcsolatok relationship-name tulajdonsága kötelező, és egyedinek kell lennie egy adott entitás összes kapcsolatában. Az egyéni nevek egyértelmű, azonosítható kapcsolatokat biztosítanak, és megőrzik az ezekből a konfigurációkból létrehozott GraphQL-séma integritását.

Formátum

{
  "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>"]
        }
      }
    }
  }
}

Kellékek

Példák

A kapcsolatok mérlegelésekor érdemes összehasonlítani a egy-a-többhöz, a több-az-egyhezés a több-a-többhöz kapcsolatok közötti különbségeket.

Egy-a-többhöz

Először is tekintsünk egy példát arra, hogy a közzétett Category entitás egy-a-többhöz kapcsolatban áll a Book entitással. Itt a számosság beállítása many. Minden Category több kapcsolódó Book entitással rendelkezhet, míg minden Book entitás csak egyetlen Category entitáshoz van társítva.

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

Ebben a példában a source.fields lista a forrás entitás (id) Category mezőjét adja meg. Ez a mező a target entitás kapcsolódó eleméhez való csatlakozásra szolgál. Ezzel szemben a target.fields lista a cél entitás (category_id) Book mezőjét határozza meg. Ez a mező a source entitás kapcsolódó eleméhez való csatlakozásra szolgál.

Ezzel a kapcsolattal az eredményként közzétett GraphQL-sémának ehhez a példához kell hasonlítania.

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

Több az egyhez

Ezután fontolja meg több az egyhez, amely a számosságot oneállítja be. A közzétett Book entitás egyetlen kapcsolódó Category entitással rendelkezhet. A Category entitás több kapcsolódó Book entitással is rendelkezhet.

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

Itt a source.fields lista azt határozza meg, hogy a forrás entitás (category_id) Book mezője a kapcsolódó cél entitás (id) Category mezőjére hivatkozik. Ezzel szemben a target.fields lista az inverz kapcsolatot határozza meg. Ezzel a kapcsolattal az eredményként kapott GraphQL-séma mostantól tartalmaz egy leképezést a könyvekről a kategóriákra.

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

Több-a-többhöz

Végül egy több-a-többhöz kapcsolat many számosságával és több metaadattal definiálva határozza meg, hogy mely adatbázis-objektumok használatával hozza létre a kapcsolatot a háttéradatbázisban. Itt a Book entitás több Author entitással is rendelkezhet, és ezzel szemben a Author entitás több Book entitással is rendelkezhet.

{
  "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": {
        ...
      }
    }
  }
}

Ebben a példában a source.fields és a target.fields egyaránt azt jelzik, hogy a kapcsolattábla a forrás (id) és a cél (Book) entitások elsődleges azonosítóját (Author) használja. A linking.object mező azt határozza meg, hogy a kapcsolat az dbo.books_authors adatbázis-objektumban van definiálva. A linking.source.fields azt is megadja, hogy a csatolási objektum book_id mezője a id entitás Book mezőjére hivatkozik, linking.target.fields pedig azt határozza meg, hogy a csatolási objektum author_id mezője a id entitás Author mezőjére hivatkozik.

Ez a példa az ehhez a példához hasonló GraphQL-sémával írható le.

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

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

Számossága

Azt adja meg, hogy az aktuális forrásentitás csak a cél entitás egyetlen példányához vagy többhez kapcsolódik-e.

Értékrend

Íme a tulajdonság engedélyezett értékeinek listája:

Cél entitás

A konfigurációban máshol definiált entitás neve, amely a kapcsolat célja.

Forrásmezők

Nem kötelező paraméter a forrásban való leképezéshez használt mező meghatározásához, a cél entitás kapcsolódó eleméhez való csatlakozáshoz.

Célmezők

Nem kötelező paraméter a forrás entitás kapcsolódó eleméhez való csatlakozáshoz használt cél- entitás leképezéséhez használt mező definiálásához.

Objektum vagy entitás csatolása

Több-a-többhöz kapcsolatok esetén annak az adatbázis-objektumnak vagy entitásnak a neve, amely a két másik entitás közötti kapcsolat meghatározásához szükséges adatokat tartalmazza.

Forrásmezők csatolása

A forrás entitáshoz kapcsolódó adatbázis-objektum vagy entitásmező neve.

Célmezők összekapcsolása

A cél entitáshoz kapcsolódó adatbázis-objektum vagy entitásmező neve.

Gyorsítótár (entitások)

Engedélyezi és konfigurálja az entitás gyorsítótárazását.

Formátum

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>
      }
    }
  }
}

Kellékek

Példák

Ebben a példában a gyorsítótár engedélyezve van, és az elemek 30 másodperc után lejárnak.

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

Engedélyezve (Gyorsítótár-entitás)

Engedélyezi az entitás gyorsítótárazását.

Adatbázis-objektum támogatása

HTTP-fejléc támogatása

Formátum

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

Példák

Ebben a példában a gyorsítótár le van tiltva.

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

TTL másodpercben (Gyorsítótár-entitás)

Az élettartam (TTL) értékét másodpercben konfigurálja a gyorsítótárazott elemekhez. Ennyi idő elteltével a rendszer automatikusan eltávolítja az elemeket a gyorsítótárból. Az alapértelmezett érték 5 másodperc.

Formátum

{
  "entities": {
    "<entity-name>": {
      "cache": {
        "ttl-seconds": <integer; inherited>
      }
    }
  }
}

Példák

Ebben a példában a gyorsítótár engedélyezve van, és az elemek 15 másodperc után lejárnak. Ha nincs megadva, ez a beállítás örökli a globális beállítást vagy az alapértelmezett beállítást.

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

Kapcsolódó tartalom

• Functions-referencia
• parancssori felület (CLI) referenciája