Udostępnij za pomocą


Entities

Ustawienia konfiguracji dla jednostek bazy danych.

Health

Property Description
entities.entity-name.health.enabled Włącza sprawdzanie kondycji jednostki (zarówno punktów końcowych REST, jak i GraphQL)
entities.entity-name.health.first Liczba wierszy zwracanych w zapytaniu sprawdzania kondycji (zakres: 1–500)
entities.entity-name.health.threshold-ms Maksymalny czas trwania w milisekundach dla zapytania sprawdzania kondycji (min. 1)

Source

Property Description
entities.entity-name.source.type Typ obiektu: table, lub viewstored-procedure
entities.entity-name.source.object Nazwa obiektu bazy danych
entities.entity-name.source.parameters Parametry procedur składowanych lub funkcji
entities.entity-name.source.key-fields Lista pól klucza podstawowego dla widoków
entities.entity-name.mappings Mapuje nazwy pól interfejsu API na kolumny bazy danych

REST

Property Description
entities.entity-name.rest.enabled Włącza interfejs REST dla tej jednostki
entities.entity-name.rest.path Trasa niestandardowa dla punktu końcowego REST
entities.entity-name.rest.methods Dozwolone metody REST: get, , postput, , patchdelete

GraphQL

Property Description
entities.entity-name.graphql.type Nazwa typu lub obiekt z elementami singular i plural
entities.entity-name.graphql.operation Typ operacji: query lub mutation
entities.entity-name.graphql.enabled Włącza narzędzie GraphQL dla tej jednostki

Permissions

Property Description
entities.entity-name.permissions[].role Ciąg nazwy roli
entities.entity-name.permissions[].actions Co najmniej jedna z nich: create, , readupdate, , deleteexecute

Relationships

Property Description
entities.entity-name.relationships.relationship-name.cardinality one lub many
entities.entity-name.relationships.relationship-name.target.entity Nazwa jednostki docelowej
entities.entity-name.relationships.relationship-name.source.fields Pola z tej jednostki używane w relacji
entities.entity-name.relationships.relationship-name.target.fields Pola z jednostki docelowej
entities.entity-name.relationships.relationship-name.linking.object Sprzężenie obiektu używanego w relacjach wiele-do-wielu
entities.entity-name.relationships.relationship-name.linking.source.fields Pola z jednostki źródłowej używanej w sprzężeniach
entities.entity-name.relationships.relationship-name.linking.target.fields Pola z jednostki docelowej używanej w sprzężeniach

Cache

Property Description
entities.entity-name.cache.enabled Włącza buforowanie odpowiedzi dla jednostki
entities.entity-name.cache.ttl-seconds Czas wygaśnięcia pamięci podręcznej w sekundach

Omówienie formatu

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

Źródło (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.{entity-name} source obiekt ✔️ Tak None

Szczegóły źródła bazy danych jednostki.

Właściwości zagnieżdżone

Parent Property Typ Required Default
entities.{entity-name}.source object ciąg ✔️ Tak None
entities.{entity-name}.source type wyliczenie (table, view, stored-procedure) ✔️ Tak None
entities.{entity-name}.source key-fields tablica ciągów ✔️ Tak* None
entities.{entity-name}.source parameters obiekt ✔️ Tak** None
  • key-fields jest wymagany tylko wtedy, gdy type ma wartość view. Wartość reprezentuje klucze podstawowe.

** parameters parametr jest wymagany tylko wtedy, gdy type parametr jest stored-procedure i tylko dla parametrów z wartościami domyślnymi. Typ danych parametru jest wnioskowany. Parametry bez wartości domyślnej można pominąć.

Tip

Jeśli obiekt należy do schematu dbo, określenie schematu jest opcjonalne. Ponadto nawiasy kwadratowe wokół nazw obiektów (na przykład dbo.Users vs. [dbo].[Users]) mogą być używane w razie potrzeby.

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

Uprawnienia (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.permissions role ciąg ✔️ Tak None

Ciąg określający nazwę roli, do której mają zastosowanie uprawnienia.

Format

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

Example

W tym przykładzie zdefiniowano rolę custom-role z uprawnieniami tylko read do User jednostki.

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

Przykłady użycia

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

Akcje (string-array Permissions entity-name entities)

Parent Property Typ Required Default
entities.permissions actions oneOf [ciąg, tablica] ✔️ Tak None

Tablica ciągów szczegółowo określa, jakie operacje są dozwolone dla skojarzonej roli.

Action Operacja SQL
* Wszystkie akcje
create Wstaw co najmniej jeden wiersz*
read Wybierz co najmniej jeden wiersz
update Modyfikowanie co najmniej jednego wiersza*
delete Usuwanie co najmniej jednego wiersza*
execute Uruchamia procedurę składowaną

* Wiele operacji jest obecnie obsługiwanych tylko w narzędziu GraphQL.

Note

W przypadku procedur składowanych akcja wieloznaczny (*) rozszerza się tylko do akcji execute. W przypadku tabel i widoków rozszerza się na create, read, updatei delete.

Format

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

Example

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

Format alternatywny (tylko ciąg, gdy type=stored-procedure)

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

Example

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

Akcje (jednostki uprawnień tablicy obiektów)

Parent Property Typ Required Default
entities.{entity-name}.permissions actions tablica ciągów ✔️ Tak None

Tablica obiektów szczegółowo określa, jakie operacje są dozwolone dla skojarzonej roli.

Note

W przypadku procedur składowanych akcja wieloznaczny (*) rozszerza się tylko na execute. W przypadku tabel/widoków rozszerza się na create, read, updatei delete.

Właściwości zagnieżdżone

Parent Property Typ Required Default
entities.{entity-name}.permissions.actions[] action ciąg ✔️ Tak None
entities.{entity-name}.permissions.actions[] fields obiekt ❌ Nie None
entities.{entity-name}.permissions.actions[] policy obiekt ❌ Nie None
entities.{entity-name}.permissions.actions[].policy database ciąg ✔️ Tak None

Format

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

Example

To uprawnienie do read uprawnień do auditorUser jednostki z ograniczeniami pól i zasad.

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

Uwagi dotyczące zasad

  • Zasady obsługują operatory OData, takie jak eq.
  • Zasady obsługują predykaty złożone przy użyciu poleceń and i or.
  • Obsługiwane tylko w przypadku akcji: create, read, updatei delete. (Nie execute)
  • Zasady filtrują wyniki, ale nie uniemożliwiają wykonywania zapytań w bazie danych.
  • Pole musi używać aliasu pola, jeśli jest mapowane.

Typ (jednostki jednostki GraphQL)

Parent Property Typ Required Default
entities.{entity-name}.graphql type obiekt ❌ Nie {entity-name}

Ustawia konwencję nazewnictwa dla jednostki w schemacie GraphQL.

Format

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

Właściwości zagnieżdżone

Parent Property Required Typ Default
entities.{entity-name}.graphql.type singular ❌ Nie ciąg None
entities.{entity-name}.graphql.type plural ❌ Nie ciąg N/A (domyślnie wartość pojedyncza)

Example

Configuration

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

Zapytanie GraphQL

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

Odpowiedź graphQL

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

Operacja (jednostki nazwy jednostki GraphQL)

Parent Property Typ Required Default
entities.{entity-name}.graphql operation ciąg wyliczenia ❌ Nie mutation

Określa, stored-procedure czy operacja jest wyświetlana pod elementem Query lub Mutation.

Note

Po ustawieniu {entity-name}.type na stored-procedurezostanie automatycznie utworzony nowy typ graphQL executeXXX. Ta operation właściwość steruje miejscem, w którym ten typ jest umieszczany w schemacie GraphQL. Nie ma żadnego wpływu funkcjonalnego, tylko higieny schematu.

Format

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

Przykład: operacja

Gdy operation jest ustawiona wartość query

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

Gdy operation jest ustawiona wartość mutation

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

Włączone (jednostki nazwy jednostki GraphQL)

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

Umożliwia deweloperom selektywne dołączanie jednostek do schematu GraphQL.

Format

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

REST (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.{entity-name}.rest enabled boolean ❌ Nie True
entities.rest path ciąg ❌ Nie /{entity-name}
entities.{entity-name}.rest methods tablica ciągów ❌ Nie* POST

* Właściwość methods dotyczy tylko stored-procedure punktów końcowych.

Format

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

Mapowania (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.{entity-name} mappings obiekt ❌ Nie None

Włącza niestandardowe aliasy lub uwidocznione nazwy dla pól obiektów bazy danych.

Important

W przypadku jednostek z włączonym językiem GraphQL skonfigurowana nazwa uwidoczniona musi spełniać wymagania dotyczące nazwy GraphQL.

Format

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

Examples

Tabela bazy danych

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

Configuration

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

Pamięć podręczna (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.{entity-name} cache obiekt ❌ Nie None

Włącza i konfiguruje buforowanie dla jednostki.

Właściwości zagnieżdżone

Parent Property Typ Required Default
entities.{entity-name}.cache enabled boolean ❌ Nie False
entities.{entity-name}.cache ttl-seconds liczba całkowita ❌ Nie -

Format

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

Note

Jeśli nie zostanie określony, ttl-seconds dziedziczy wartość globalną ustawioną w obszarze runtime.cache.

Example

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

Relacje (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.{entity-name} relationships obiekt ❌ Nie None

Konfiguruje sposób, w jaki jednostki GraphQL są powiązane z innymi uwidocznionych jednostkami. Aby uzyskać więcej informacji, zobacz Podział relacji konstruktora interfejsu API danych.

Note

Właściwość relationship-name dla każdej relacji musi być unikatowa we wszystkich relacjach dla tej jednostki.

Właściwości zagnieżdżone

Te właściwości są używane w różnych kombinacjach w zależności od kardynalności relacji.

Parent Property Typ Required Default
entities.{entity-name}.relationships cardinality ciąg ✔️ Tak None
entities.{entity-name}.relationships target.entity ciąg ✔️ Tak None
entities.{entity-name}.relationships target.fields tablica ciągów ❌ Nie None
entities.{entity-name}.relationships source.fields tablica ciągów ❌ Nie None
entities.{entity-name}.relationships linking.object ciąg ❌ Nie None
entities.{entity-name}.relationships linking.source.fields tablica ciągów ❌ Nie None
entities.{entity-name}.relationships linking.target.fields tablica ciągów ❌ Nie 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 Jedna jednostka kategorii może odnosić się do wielu jednostek zadań do wykonania
many-to-one one Wiele jednostek zadań do wykonania może odnosić się do jednej jednostki kategorii
many-to-many many Jedna jednostka zadań do wykonania może odnosić się do wielu jednostek użytkowników, a jedna jednostka użytkownika może odnosić się do wielu jednostek zadań do wykonania

Przykład: kardynalność jeden do jednego

Każda z nich jest powiązana z dokładnie jedną Profilewartością , a każda User z nich User ma dokładnie jeden powiązany element Profile.

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

Schemat GraphQL

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

Command-line

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

Przykład: kardynalność jeden do wielu

Element Category może mieć co najmniej jedną powiązaną Book jednostkę, a każda z nich Book może mieć jeden powiązany element Category.

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

Schemat GraphQL

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

Wiersz polecenia

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

Przykład: kardynalność wiele-do-jednego

Wiele Book jednostek może mieć jeden powiązany Categoryelement , a element Category może zawierać co najmniej jeden powiązany Book wpis.

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

Schemat GraphQL

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

Wiersz polecenia

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

Przykład: kardynalność wiele-do-wielu

Wiele Book jednostek może mieć wiele powiązanych Author jednostek, podczas gdy wiele Author jednostek może mieć wiele powiązanych Book wpisów.

Note

Ta relacja jest możliwa w przypadku trzeciej tabeli , dbo.books_authorsktóra jest nazywana obiektem łączenia.

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

Schemat GraphQL

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

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

Wiersz polecenia

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"

Kondycja (jednostki o nazwie jednostki)

Parent Property Typ Required Default
entities.{entity-name} health obiekt ❌ Nie None

Włącza i konfiguruje kontrole kondycji dla jednostki.

Właściwości zagnieżdżone

Parent Property Typ Required Default
entities.{entity-name}.health enabled boolean ❌ Nie true
entities.{entity-name}.health first liczba całkowita ❌ Nie 100
entities.{entity-name}.health threshold-ms liczba całkowita ❌ Nie 1000

Example

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

Note

Wartość first musi być mniejsza lub równa ustawieniu runtime.pagination.max-page-size . Mniejsze wartości ułatwiają szybsze sprawdzanie kondycji.

Important

Procedury składowane są automatycznie wykluczane z kontroli kondycji jednostki, ponieważ wymagają parametrów i mogą nie być deterministyczne.