Sélection de champ (projection) dans REST

La projection vous permet de retourner uniquement ce dont votre client a réellement besoin. Les charges utiles plus petites améliorent les performances, réduisent les coûts réseau et réduisent la surcharge d’analyse côté client. Le générateur d’API de données (DAB) implémente la projection pour REST via le $select paramètre de requête.

Note

Les noms des paramètres de requête REST (y compris $select) respectent la casse. Les noms de champs respectent également la casse en fonction de ce que vous avez configuré ou exposé.

Accédez à la version GraphQL de ce document.

Sélection de base

Motif

GET /api/{entity}?$select=FieldA,FieldB,FieldC

S’il $select est omis, DAB retourne tous les champs que le rôle de l’appelant est autorisé à lire (soumis à include des autorisations au niveau du champ et à la exclude configuration). Il n’y a pas de jeton générique comme *; omettre $select est la façon dont vous demandez la forme autorisée complète.

Examples

# Return all accessible fields
GET /api/author

# Return only first_name
GET /api/author?$select=first_name

# Return only first_name and last_name
GET /api/author?$select=first_name,last_name

Colonnes internes et de réponse

Vous n’êtes pas obligé de projeter des champs de clé primaire ou de classement. S’ils ne sont pas omis, ils n’apparaissent pas dans la réponse JSON. Toutefois, DAB peut extraire en interne des colonnes supplémentaires nécessaires pour appliquer des stratégies de sécurité (filtres au niveau des lignes, masques de champ) et gérer des curseurs de pagination ($after / nextLink).

Note

Ces colonnes extraites en interne sont supprimées avant la réponse, sauf si vous les demandez explicitement.

Example

GET /api/book?$select=id,title&$orderby=publisher_id desc&$first=5

SQL conceptuel

SELECT TOP (6) -- first (5) + 1 probe row for paging
  [b].[id],
  [b].[sku_title] AS title
FROM dbo.books AS [b]
ORDER BY [b].[publisher_id] DESC, [b].[id] ASC;

Réponse

{
  "value": [
    { "id": 101, "title": "Example 1" },
    { "id": 77,  "title": "Example 2" },
    { "id": 42,  "title": "Example 3" },
    { "id": 33,  "title": "Example 4" },
    { "id": 5,   "title": "Example 5" }
  ],
  "nextLink": "..."
}

En savoir plus sur la pagination et le mot clé after.

Les colonnes internes supplémentaires et la sixième ligne de sonde ne sont pas visibles dans la charge utile.

Procédures stockées

Pour les entités stockées sauvegardées, $select n’est pas interprétée comme une clause de projection. Au lieu de cela, les paires clé/valeur de chaîne de requête (à l’exception des paramètres système reconnus comme $filter, $orderbyetc.) sont traitées comme des paramètres de procédure stockée. $select n’a aucun effet ; le jeu de résultats de la procédure définit la forme.

Exemple de configuration

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Voir aussi

Concept	REST	GraphQL	Objectif
Projection	$select	Éléments	Choisir les champs à retourner
Filtrage	$filter	filtre	Restreindre les lignes par condition
Tri	$orderby	orderBy	Définir l’ordre de tri
Taille de la page	$first	first	Limiter le nombre d’éléments par page
Continuation	$after	après	Continuer à partir de la dernière page à l’aide d’un curseur

Note

Les mots clés REST commencent par $les conventions OData suivantes.