Objets de base de données développés dans le générateur d’API de données

Le générateur d’API de données prend en charge les vues et les procédures stockées comme alternatives au mappage à des tables ou conteneurs de base de données. Ces objets de base de données distincts nécessitent une configuration personnalisée pour mapper en toute transparence aux points de terminaison REST ou GraphQL. Une configuration personnalisée est nécessaire pour utiliser le générateur d’API de données avec des vues et des procédures stockées.

Cet article comprend une répartition de l’utilisation des vues et des procédures stockées avec le générateur d’API de données.

Affichage

Les vues peuvent être utilisées de manière similaire à la façon dont une table peut être utilisée dans le générateur d’API de données. L’utilisation de l’affichage doit être définie en spécifiant le type source de l’entité comme view. En plus de cela, la propriété key-fields doit être fournie, afin que le générateur d’API de données sache comment il peut identifier et retourner un seul élément, si nécessaire.

Si vous avez une vue, par exemple dbo.vw_books_details elle peut être exposée à l’aide de la commande dab suivante :

dab add BookDetail --source dbo.vw_books_details --source.type View --source.key-fields "id" --permissions "anonymous:read"

Note

--source.key-fields est obligatoire pour les vues lors de la génération de la configuration via l’interface CLI.

Le fichier dab-config.json ressemble à l’exemple suivant :

"BookDetail": {
  "source": {
    "type": "view",
    "object": "dbo.vw_books_details",
    "key-fields": [ "id" ]
  },
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

Note

Notez que vous devez configurer l’autorisation en conséquence avec la possibilité de la vue d’être mise à jour ou non. Si une vue n’est pas modifiable, vous devez autoriser uniquement un accès en lecture à l’entité en fonction de cette vue.

Prise en charge REST des vues

Une vue, du point de vue REST, se comporte comme une table. Toutes les opérations REST sont prises en charge.

Prise en charge de GraphQL pour les vues

Une vue, du point de vue GraphQL, se comporte comme une table. Toutes les opérations GraphQL sont prises en charge.

Procédures stockées

Les procédures stockées peuvent être utilisées en tant qu’objets liés aux entités exposées par le générateur d’API de données. L’utilisation de la procédure stockée doit être définie en spécifiant que le type source de l’entité est stored-procedure.

Note

Le générateur d’API de données prend en charge les procédures stockées pour les bases de données relationnelles (par exemple, MSSQL), mais pas pour les bases de données non relationnelles (c’est-à-dire NoSQL).

Si vous avez une procédure stockée, par exemple dbo.stp_get_all_cowritten_books_by_author elle peut être exposée à l’aide de la commande dab suivante :

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "get" --graphql.operation "query"

Le fichier dab-config.json ressemble à l’exemple suivant :

"GetCowrittenBooksByAuthor": {
  "source": {
    "type": "stored-procedure",
    "object": "dbo.stp_get_all_cowritten_books_by_author",
    "parameters": {
      "searchType": "s"
    }
  },
  "rest": {
    "methods": [ "GET" ]
  },
  "graphql": {
    "operation": "query"
  },
  "permissions": [{
   "role": "anonymous",
    "actions": [ "execute" ]
  }]
}

La parameters définit quels paramètres doivent être exposés et fournit également des valeurs par défaut à passer aux paramètres de procédure stockée, si ces paramètres ne sont pas fournis dans la requête HTTP.

Limitations

• Seul le premier jeu de résultats retourné par la procédure stockée est utilisé par le générateur d’API de données.
• Seules les procédures stockées dont les métadonnées pour le premier jeu de résultats décrit par sys.dm_exec_describe_first_result_set sont prises en charge.
• Pour les points de terminaison REST et GraphQL : lorsqu’un paramètre de procédure stockée est spécifié à la fois dans le fichier de configuration et dans la chaîne de requête d’URL, le paramètre de la chaîne de requête URL est prioritaire.
• Les entités sauvegardées par une procédure stockée ne disposent pas de toutes les fonctionnalités automatiquement fournies pour les entités sauvegardées par des tables, des collections ou des vues.
  • Les entités sauvegardées de procédure stockée ne prennent pas en charge la pagination, l’ordre ou le filtrage. De même, ces entités ne prennent pas en charge le retour d’éléments spécifiés par les valeurs de clé primaire.
  • Les règles d’autorisation au niveau du champ/paramètre ne sont pas prises en charge.

Prise en charge REST des procédures stockées

Le comportement du point de terminaison REST, pour l’entité sauvegardée de procédure stockée, peut être configuré pour prendre en charge un ou plusieurs verbes HTTP (GET, POST, PUT, PATCH, DELETE). La section REST de l’entité ressemble à l’exemple suivant :

"rest": {
  "methods": [ "GET", "POST" ]
}

Toutes les requêtes REST pour l’entité échouent avec méthode HTTP 405 non autorisée lorsqu’une méthode HTTP non répertoriée dans la configuration est utilisée. Par exemple, l’exécution d’une requête PUT échoue avec le code d’erreur 405. Si la section methods est exclue de la configuration REST de l’entité, la méthode par défaut POST est déduite. Pour désactiver le point de terminaison REST de cette entité, configurez "rest": false et toutes les requêtes REST sur l’entité de procédure stockée échouent avec HTTP 404 Introuvable.

Si la procédure stockée accepte des paramètres, les paramètres peuvent être transmis dans la chaîne de requête d’URL lors de l’appel du point de terminaison REST avec le verbe HTTP GET. Par exemple :

GET http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov

Les procédures stockées exécutées à l’aide d’autres verbes HTTP tels que POST, PUT, PATCH, DELETE nécessitent que les paramètres soient transmis en tant que JSON dans le corps de la requête. Par exemple :

POST http://<dab-server>/api/GetCowrittenBooksByAuthor

{
  "author": "isaac asimov"
}

Prise en charge de GraphQL pour les procédures stockées

L’exécution de procédure stockée dans GraphQL peut être configurée à l’aide de l’option graphql d’une entité stockée sauvegardée par une procédure stockée. La définition explicite de l’opération de l’entité vous permet de représenter une procédure stockée dans le schéma GraphQL d’une manière qui s’aligne sur le comportement de la procédure stockée.

Note

GraphQL nécessite'un élément Query soit présent dans le schéma. Si vous exposez uniquement des procédures stockées, veillez à avoir au moins l’une d’entre elles prenant en charge l’opération de query ; sinon, vous obtiendrez une erreur GraphQL comme The object type Query has to at least define one field in order to be valid.

La définition d’une valeur pour l’opération entraîne la création d’une opération de mutation.

Par exemple, l’utilisation de la valeur query pour l’option operation entraîne la résolution de la procédure stockée en tant que champ de requête dans le schéma GraphQL.

Utilisation de l’interface CLI :

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "GET" --graphql.operation "query"

Configuration du runtime :

"graphql": {
  "operation": "query"
}

Composants de schéma GraphQL : type et champ de requête :

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

Dans le schéma, les opérations de requête et de mutation pour les procédures stockées ont execute comme préfixe. Pour la procédure stockée précédente, le champ de nom de requête exact généré est executeGetCowrittenBooksByAuthor. Le type GraphQL généré est :

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

Vous pouvez également définir operation sur mutation afin qu’un champ de mutation représente la procédure stockée dans le schéma GraphQL. La commande dab update peut être utilisée pour modifier la operation:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Configuration du runtime :

"graphql": {
  "operation": "mutation"
}

Le schéma GraphQL généré est :

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

Si la procédure stockée accepte des paramètres, ces paramètres peuvent être passés en tant que paramètre de la requête ou de la mutation. Par exemple :

query {
  executeGetCowrittenBooksByAuthor(author:"asimov")
   {
    id
    title
    pages
    year
  }
}

Contenu connexe

• informations de référence sur la configuration
• installer l’interface CLI