Freigeben über


Entities

Konfigurationseinstellungen für Datenbankentitäten.

Health

Property Description
entities.entity-name.health.enabled Aktiviert Integritätsprüfungen für die Entität (sowohl REST- als auch GraphQL-Endpunkte)
entities.entity-name.health.first Anzahl der in der Integritätsprüfungsabfrage zurückgegebenen Zeilen (Bereich: 1-500)
entities.entity-name.health.threshold-ms Maximale Dauer in Millisekunden für die Integritätsprüfungsabfrage (min: 1)

Source

Property Description
entities.entity-name.source.type Objekttyp: table, , viewoder stored-procedure
entities.entity-name.source.object Name des Datenbankobjekts
entities.entity-name.source.parameters Parameter für gespeicherte Prozeduren oder Funktionen
entities.entity-name.source.key-fields Liste der Primärschlüsselfelder für Ansichten
entities.entity-name.mappings Ordnet API-Feldnamen Datenbankspalten zu

REST

Property Description
entities.entity-name.rest.enabled Aktiviert REST für diese Entität
entities.entity-name.rest.path Benutzerdefinierte Route für REST-Endpunkt
entities.entity-name.rest.methods Zulässige REST-Methoden: get, , postput, patchdelete

GraphQL

Property Description
entities.entity-name.graphql.type Typname oder Objekt mit singular und plural
entities.entity-name.graphql.operation Vorgangstyp: query oder mutation
entities.entity-name.graphql.enabled Aktiviert GraphQL für diese Entität

Permissions

Property Description
entities.entity-name.permissions[].role Rollennamenzeichenfolge
entities.entity-name.permissions[].actions Eine oder mehrere von: create, read, update, , deleteexecute

Relationships

Property Description
entities.entity-name.relationships.relationship-name.cardinality one oder many
entities.entity-name.relationships.relationship-name.target.entity Name der Zielentität
entities.entity-name.relationships.relationship-name.source.fields Felder aus dieser Entität, die in der Beziehung verwendet werden
entities.entity-name.relationships.relationship-name.target.fields Felder aus Zielentität
entities.entity-name.relationships.relationship-name.linking.object Join-Objekt, das für n:n-Beziehungen verwendet wird
entities.entity-name.relationships.relationship-name.linking.source.fields Felder aus der Quellentität, die in der Verknüpfung verwendet wird
entities.entity-name.relationships.relationship-name.linking.target.fields Felder aus der Zielentität, die in der Verknüpfung verwendet wird

Cache

Property Description
entities.entity-name.cache.enabled Aktiviert das Zwischenspeichern von Antworten für die Entität.
entities.entity-name.cache.ttl-seconds Zwischenspeichern von Zeit-zu-Live-Zeit in Sekunden

Formatübersicht

{
  "entities": {
    "{entity-name}": {
      "rest": {
        "enabled": <boolean> // default: true
        "path": <string> // default: "{entity-name}"
        "methods": ["GET", "POST"] // default: ["GET", "POST"]
      },
      "graphql": {
        "enabled": <boolean> // default: true
        "type": {
          "singular": <string>,
          "plural": <string>
        },
        "operation": "query" | "mutation" // default: "query"
      },
      "source": {
        "object": <string>,
        "type": "view" | "stored-procedure" | "table",
        "key-fields": [<string>], // primary keys for the view
        "parameters": { // only for stored-procedure
          "<parameter-name>": <default-value>,
          "<parameter-name>": <default-value>
        }
      },
      "mappings": {
        "<database-field-name>": <string>
      },
      "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>]
        }
      },
      "permissions": [
        {
          "role": "anonymous" | "authenticated" | <custom-role>,
          "actions": ["create", "read", "update", "delete", "execute", "*"],
          "fields": {
            "include": [<string>],
            "exclude": [<string>]
          },
          "policy": {
            "database": <string>
          }
        }
      ]
    }
  }
}

Quelle (Entitätsnamenentitäten)

Parent Property Type Required Default
entities.{entity-name} source object ✔️ Ja None

Die Datenbankquelldetails der Entität.

Verschachtelte Eigenschaften

Parent Property Type Required Default
entities.{entity-name}.source object string ✔️ Ja None
entities.{entity-name}.source type Enumeration (table, view, stored-procedure) ✔️ Ja None
entities.{entity-name}.source key-fields Zeichenfolgenarray ✔️ Ja* None
entities.{entity-name}.source parameters object ✔️ Ja** None
  • key-fields ist nur erforderlich, wenn type dies der Zeitpunkt ist view. Der Wert stellt die Primärschlüssel dar.

** parameters ist nur erforderlich, wenn type und stored-procedure nur für Parameter mit Standardwerten. Der Datentyp des Parameters wird abgeleitet. Parameter ohne Standard können weggelassen werden.

Tip

Wenn das Objekt zum dbo Schema gehört, ist die Angabe des Schemas optional. Darüber hinaus können eckige Klammern um Objektnamen (z dbo.Users . B. vs. [dbo].[Users]) bei Bedarf verwendet werden.

Format

{
  "entities": {
    "{entity-name}": {
      "source": {
        "object": <string>,
        "type": <"view" | "stored-procedure" | "table">,
        "key-fields": [ <string> ], // primary keys of the view
        "parameters": { // only for option stored-procedure parameters
          "<parameter-name-1>": <default-value>
          "<parameter-name-2>": <default-value>
        }
      }
    }
  }
}

Berechtigungen (Entitätsnamenentitäten)

Parent Property Type Required Default
entities.permissions role string ✔️ Ja None

Eine Zeichenfolge, die den Namen der Rolle angibt, für die Berechtigungen gelten.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "role": <"anonymous" | "authenticated" | "custom-role">
        }
      ]
    }
  }
}

Example

In diesem Beispiel wird die Rolle custom-role mit nur read Berechtigungen für die User Entität definiert.

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

Verwendungsbeispiele

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

Aktionen (Entitätsentitäten mit Zeichenfolgenarrayberechtigungen)

Parent Property Type Required Default
entities.permissions actions oneOf [string, array] ✔️ Ja None

Ein Zeichenfolgenarray, das angibt, welche Vorgänge für die zugeordnete Rolle zulässig sind.

Action SQL-Vorgang
* Alle Aktionen
create Einfügen einer oder mehrerer* Zeilen
read Auswählen einer oder mehrerer Zeilen
update Ändern einer oder mehrerer* Zeilen
delete Löschen einer oder mehrerer Zeilen*
execute Führt eine gespeicherte Prozedur aus.

* Mehrere Vorgänge werden derzeit nur in GraphQL unterstützt.

Note

Bei gespeicherten Prozeduren wird die Aktion "Wildcard(*) nur auf die execute Aktion erweitert. Für Tabellen und Ansichten wird sie auf create, read, updateund deleteerweitert.

Format

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ <string> ]
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": [ "*" ] // equivalent to create, read, update, delete
        }
      ]
    }
  }
}

Alternatives Format (nur Zeichenfolge, wenn type=stored-procedure)

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": <string>
        }
      ]
    }
  }
}

Example

{
  "entities": {
    "{entity-name}": {
      "permissions": [
        {
          "actions": "*" // equivalent to execute
        }
      ]
    }
  }
}

Aktionen (Entitäten mit Objektarrayberechtigungen)

Parent Property Type Required Default
entities.{entity-name}.permissions actions Zeichenfolgenarray ✔️ Ja None

Ein Objektarray, das angibt, welche Vorgänge für die zugeordnete Rolle zulässig sind.

Note

Bei gespeicherten Prozeduren wird die Wildcardaktion (*) nur auf executeerweitert. Bei Tabellen/Ansichten wird sie auf create, read, updateund deleteerweitert.

Verschachtelte Eigenschaften

Parent Property Type Required Default
entities.{entity-name}.permissions.actions[] action string ✔️ Ja None
entities.{entity-name}.permissions.actions[] fields object ❌ Nein None
entities.{entity-name}.permissions.actions[] policy object ❌ Nein None
entities.{entity-name}.permissions.actions[].policy database string ✔️ Ja None

Format

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

Example

Dadurch wird die Berechtigung für read die auditor Entität mit Feld- und Richtlinieneinschränkungen gewährtUser.

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

Richtliniennotizen

  • Richtlinien unterstützen OData-Operatoren wie eq.
  • Richtlinien unterstützen zusammengesetzte Prädikate unter Verwendung and und or.
  • Nur für Aktionen unterstützt: create, , read, updateund delete. (Nicht execute)
  • Richtlinien filtern Ergebnisse, verhindern jedoch die Abfrageausführung in der Datenbank nicht.
  • Das Feld muss den Feldalias verwenden, wenn es zugeordnet ist.

Typ (GraphQL-Entitätennamentitäten)

Parent Property Type Required Default
entities.{entity-name}.graphql type object ❌ Nein {entity-name}

Legt die Benennungskonvention für eine Entität im GraphQL-Schema fest.

Format

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

Verschachtelte Eigenschaften

Parent Property Required Type Default
entities.{entity-name}.graphql.type singular ❌ Nein string None
entities.{entity-name}.graphql.type plural ❌ Nein string N/A (Standardwert für singular-Wert)

Example

Configuration

{
  "entities": {
    "User": {
      "graphql": {
        "type": {
          "singular": "User",
          "plural": "Users"
        }
      }
    }
  }
}

GraphQL-Abfrage

{
  Users {
    items {
      id
      name
      age
      isAdmin
    }
  }
}

GraphQL-Antwort

{
  "data": {
    "Users": {
      "items": [
        {
          "id": 1,
          "name": "Alice",
          "age": 30,
          "isAdmin": true
        },
        {
          "id": 2,
          "name": "Bob",
          "age": 25,
          "isAdmin": false
        }
        // ...
      ]
    }
  }
}

Vorgang (GraphQL-Entitätennamentitäten)

Parent Property Type Required Default
entities.{entity-name}.graphql operation Enumerationszeichenfolge ❌ Nein mutation

Legt fest, ob der stored-procedure Vorgang unter dem oder dem QueryMutation.

Note

Wenn {entity-name}.type dieser auf festgelegt stored-procedureist, wird automatisch ein neuer GraphQL-Typ executeXXX erstellt. Diese operation Eigenschaft steuert, wo dieser Typ im GraphQL-Schema platziert wird. Es gibt keine funktionalen Auswirkungen, nur die Schemahygiene.

Format

{
  "entities": {
    "{entity-name}": {
      "graphql": {
        "operation": "query" | "mutation"
      }
    }
  }
}

Beispiel: Vorgang

Wann operation ist auf query

type Query {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Wann operation ist auf mutation

type Mutation {
  executeGetUserDetails(userId: Int!): GetUserDetailsResponse
}

Aktiviert (GraphQL-Entitätennamentitäten)

Parent Property Type Required Default
entities.{entity-name}.graphql enabled boolean ❌ Nein True

Ermöglicht Entwicklern selektiv das Einschließen von Entitäten im GraphQL-Schema.

Format

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

REST (Entitätsnamenentitäten)

Parent Property Type Required Default
entities.{entity-name}.rest enabled boolean ❌ Nein True
entities.rest path string ❌ Nein /{entity-name}
entities.{entity-name}.rest methods Zeichenfolgenarray ❌ Nein* POST

* Die methods Eigenschaft gilt nur für stored-procedure Endpunkte.

Format

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

Zuordnungen (Entitätsnamenentitäten)

Parent Property Type Required Default
entities.{entity-name} mappings object ❌ Nein None

Aktiviert benutzerdefinierte Aliase oder offengelegte Namen für Datenbankobjektfelder.

Important

Für Entitäten mit aktivierter GraphQL-Eigenschaft muss der konfigurierte Name der GraphQL-Namensanforderungen entsprechen.

Format

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

Examples

Datenbanktabelle

CREATE TABLE Books
(
  id INT,
  sku_title VARCHAR(50),
  sku_status VARCHAR(50),
)

Configuration

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

Cache (Entitätsnamenentitäten)

Parent Property Type Required Default
entities.{entity-name} cache object ❌ Nein None

Aktiviert und konfiguriert die Zwischenspeicherung für die Entität.

Verschachtelte Eigenschaften

Parent Property Type Required Default
entities.{entity-name}.cache enabled boolean ❌ Nein False
entities.{entity-name}.cache ttl-seconds integer ❌ Nein -

Format

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

Note

Wenn sie nicht angegeben ist, ttl-seconds erbt der unter festgelegte runtime.cacheglobale Wert.

Example

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

Beziehungen (Entitätsnamenentitäten)

Parent Property Type Required Default
entities.{entity-name} relationships object ❌ Nein None

Konfiguriert, wie GraphQL-Entitäten mit anderen verfügbar gemachten Entitäten verknüpft sind. Weitere Informationen finden Sie unter Aufschlüsselung von Daten-API-Generator-Beziehungen.

Note

Die relationship-name Eigenschaft für jede Beziehung muss für alle Beziehungen für diese Entität eindeutig sein.

Verschachtelte Eigenschaften

Diese Eigenschaften werden je nach Beziehungskardinalität in unterschiedlichen Kombinationen verwendet.

Parent Property Type Required Default
entities.{entity-name}.relationships cardinality string ✔️ Ja None
entities.{entity-name}.relationships target.entity string ✔️ Ja None
entities.{entity-name}.relationships target.fields Zeichenfolgenarray ❌ Nein None
entities.{entity-name}.relationships source.fields Zeichenfolgenarray ❌ Nein None
entities.{entity-name}.relationships linking.object string ❌ Nein None
entities.{entity-name}.relationships linking.source.fields Zeichenfolgenarray ❌ Nein None
entities.{entity-name}.relationships linking.target.fields Zeichenfolgenarray ❌ Nein None

Format

{
  "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>"]
        }
      }
    }
  }
}
Relationship Cardinality Example
one-to-many many Eine Kategorieentität kann sich auf viele Todo-Entitäten beziehen.
many-to-one one Viele Todo-Entitäten können sich auf eine Kategorieentität beziehen.
many-to-many many Eine Todo-Entität kann sich auf viele Benutzerentitäten beziehen, und eine Benutzerentität kann sich auf viele Todo-Entitäten beziehen.

Beispiel: 1:1-Kardinalität

Jeder Profile ist mit genau einem Userverknüpften , und jeder User hat genau ein verwandtes .Profile

{
  "entities": {
    "User": {
      "relationships": {
        "user_profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    },
    "Profile": {
      ...
    }
  }
}

GraphQL-Schema

type User
{
  id: Int!
  ...
  profile: Profile
}

Command-line

dab update User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Beispiel: 1:n-Kardinalität

A Category kann eine oder mehrere verwandte Book Entitäten aufweisen, während jedes Book eine verwandte CategoryEntität aufweisen kann.

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

GraphQL-Schema

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

Befehlszeile

dab update Category \
  --relationship category_books \
  --target.entity Book \
  --cardinality many \
  --relationship.fields "id:category_id"

Beispiel: n:1-Kardinalität

Viele Book Entitäten können eine verwandte CategoryEntität haben, während eine Category oder mehrere verwandte Book Einträge enthalten kann.

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

GraphQL-Schema

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

Befehlszeile

dab update Book \
  --relationship books_category \
  --target.entity "Category" \
  --cardinality one \
  --relationship.fields "category_id:id"

Beispiel: n:n-Kardinalität

Viele Book Entitäten können viele verwandte Author Entitäten haben, während viele Author Entitäten viele verwandte Book Einträge enthalten können.

Note

Diese Beziehung ist mit einer dritten Tabelle möglich, dbo.books_authorsauf die wir als verknüpfungsobjekt bezeichnen.

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

GraphQL-Schema

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

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

Befehlszeile

dab update Book \
  --relationship books_authors \
  --target.entity "Author" \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object "dbo.books_authors" \
  --linking.source.fields "book_id" \
  --linking.target.fields "author_id"

Integrität (Entitätsnamentitäten)

Parent Property Type Required Default
entities.{entity-name} health object ❌ Nein None

Aktiviert und konfiguriert Integritätsprüfungen für die Entität.

Verschachtelte Eigenschaften

Parent Property Type Required Default
entities.{entity-name}.health enabled boolean ❌ Nein true
entities.{entity-name}.health first integer ❌ Nein 100
entities.{entity-name}.health threshold-ms integer ❌ Nein 1000

Example

{
  "entities": {
    "Book": {
      "health": {
        "enabled": true,
        "first": 3,
        "threshold-ms": 500
      }
    }
  }
}

Note

Der first Wert muss kleiner oder gleich der runtime.pagination.max-page-size Einstellung sein. Kleinere Werte helfen, Integritätsprüfungen schneller abzuschließen.

Important

Gespeicherte Prozeduren werden automatisch von entitätsintegritätsprüfungen ausgeschlossen, da sie Parameter erfordern und möglicherweise nicht deterministisch sind.