Modèles de données pour REST APIs

Dans API Gateway, un modèle définit la structure de données d'une charge utile. Dans API Gateway, les modèles sont définis à l'aide du brouillon de JSON schéma 4. L'JSONobjet suivant est un exemple de données dans l'exemple d'une animalerie.

{
    "id": 1,
    "type": "dog",
    "price": 249.99
}

Les données contiennent les éléments id, type et price de l'animal de compagnie. Un modèle de ces données vous permet de :

• Utiliser la validation de base des demandes.

• Créer des modèles de mappage pour la transformation des données.

• Créez un type de données défini par l'utilisateur (UDT) lorsque vous générez unSDK.

Dans ce modèle :

1. L'$schemaobjet représente un identifiant de version de JSON schéma valide. Ce schéma est le projet de JSON schéma v4.

2. L'objet title est un identifiant du modèle lisible à l'œil. Ce titre est PetStoreModel.

3. Le mot clé de validation required requiert type et price pour la validation de base des demandes.

4. Les propriétés (properties) du modèle sont id, type et price. Chaque objet possède des propriétés qui sont décrites dans le modèle.

5. L'objet type ne peut avoir que les valeurs dog, cat ou fish.

6. L'objet price est un nombre limité entre un minimum de 25 et un maximum de 500.

PetStore modèle

1 {
2 "$schema": "http://json-schema.org/draft-04/schema#",
3  "title": "PetStoreModel",
4  "type" : "object",
5  "required" : [ "price", "type" ],
6  "properties" : {
7    "id" : {
8      "type" : "integer"
9    },
10    "type" : {
11      "type" : "string",
12      "enum" : [ "dog", "cat", "fish" ]
13    },
14    "price" : {
15      "type" : "number",
16      "minimum" : 25.0,
17      "maximum" : 500.0
18    }
19  }
20 }

Dans ce modèle :

1. Sur la ligne 2, l'$schemaobjet représente un identifiant de version de JSON schéma valide. Ce schéma est le projet de JSON schéma v4.

2. Ligne 3, l'objet title est un identifiant lisible du modèle. Ce titre est PetStoreModel.

3. Ligne 5, le mot clé de validation required requiert type et price pour la validation de base des demandes.

4. Lignes 6 à 17, les propriétés (properties) du modèle sont id, type et price. Chaque objet possède des propriétés qui sont décrites dans le modèle.

5. Ligne 12, l'objet type ne peut avoir que les valeurs dog, cat ou fish.

6. Lignes 14 à 17, l'objet price est un nombre limité entre un minimum de 25 et un maximum de 500.

Création de modèles plus complexes

Vous pouvez utiliser la primitive $ref pour créer des définitions réutilisables pour des modèles plus longs. Par exemple, vous pouvez créer une définition appelée Price dans la section definitions décrivant l'objet price. La valeur de $ref est la définition Price.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStoreModelReUsableRef",
  "required" : ["price", "type" ],
  "type" : "object",
  "properties" : {
    "id" : {
      "type" : "integer"
    },
    "type" : {
      "type" : "string",
      "enum" : [ "dog", "cat", "fish" ]
    },
    "price" : {
        "$ref": "#/definitions/Price"
    }
  },
  "definitions" : {
      "Price": {
        "type" : "number",
        "minimum" : 25.0,
        "maximum" : 500.0
            }
      }
}

Vous pouvez également référencer un autre schéma de modèle défini dans un fichier de modèle externe. Définissez la valeur de la propriété $ref en fonction de l'emplacement du modèle. Dans l'exemple suivant, le Price modèle est défini dans le PetStorePrice modèle dans APIa1234.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStorePrice",
  "type": "number",
  "minimum": 25,
  "maximum": 500
}

Le modèle le plus long peut référencer le modèle PetStorePrice.

{
  "$schema" : "http://json-schema.org/draft-04/schema#",
  "title" : "PetStoreModelReusableRefAPI",
  "required" : [ "price", "type" ],
  "type" : "object",
  "properties" : {
    "id" : {
      "type" : "integer"
    },
    "type" : {
      "type" : "string",
      "enum" : [ "dog", "cat", "fish" ]
    },
    "price" : {
        "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice"
    }
  }
}

Utilisation de modèles de données de sortie

Si vous transformez vos données, vous pouvez définir un modèle de charge utile dans la réponse d'intégration. Un modèle de charge utile peut être utilisé lorsque vous générez unSDK. Pour les langages fortement typés, tels que Java, Objective-C ou Swift, l'objet correspond à un type de données défini par l'utilisateur (). UDT APIGateway crée un UDT si vous lui fournissez un modèle de données lorsque vous générez unSDK. Pour plus d'informations sur les transformations de données, consultez Modèles de mappage pour REST APIs.

L'exemple suivant montre les données de sortie d'une réponse d'intégration.

{
[
  {
    "description" : "Item 1 is a dog.",
    "askingPrice" : 249.99
  },
  {
    "description" : "Item 2 is a cat.",
    "askingPrice" : 124.99
  },
  {
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }
]
}

L'exemple suivant est un modèle de charge utile qui décrit les données de sortie.

{
"$schema": "http://json-schema.org/draft-04/schema#",
  "title": ”PetStoreOutputModel",
  "type" : "object",
  "required" : [ "description", "askingPrice" ],
  "properties" : {
    "description" : {
      "type" : "string"
    },
    "askingPrice" : {
      "type" : "number",
      "minimum" : 25.0,
      "maximum" : 500.0
    }
  }
}

Avec ce modèle, vous pouvez appeler an SDK pour récupérer les valeurs description des askingPrice propriétés et en lisant les PetStoreOutputModel[i].askingPrice propriétés PetStoreOutputModel[i].description et. Si aucun modèle n'est fourni, API Gateway utilise le modèle vide pour créer un modèle par défautUDT.

Étapes suivantes

• Cette section fournit des ressources que vous pouvez utiliser pour en apprendre davantage sur les concepts présentés dans cette rubrique.

  Vous pouvez suivre les didacticiels de validation des demandes :

  • Configurer la validation des demandes à l'aide de la console API Gateway

  • Configurez la validation de base des demandes à l'aide du AWS CLI

  • Configurer la validation de base des demandes à l'aide d'une API définition ouverte

• Vous pouvez obtenir plus d'informations sur la transformation des données et les modèles de mappage, Modèles de mappage pour REST APIs.

• Vous pouvez également voir des modèles de données plus complexes. veuillez consulter Exemples de modèles de données et de modèles de mappage pour API Gateway.