Datenmodelle für REST APIs

In API Gateway definiert ein Modell die Datenstruktur einer Nutzlast. In API Gateway werden Modelle mithilfe des JSONSchemaentwurfs 4 definiert. Das folgende JSON Objekt sind Beispieldaten im Pet Store-Beispiel.

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

Die Daten enthalten die id, den type und den price des Haustiers. Ein Modell dieser Daten ermöglicht Ihnen Folgendes:

• Verwenden der grundlegenden Anforderungsvalidierung.

• Erstellen von Zuweisungsvorlagen für die Datentransformation.

• Erstellen Sie einen benutzerdefinierten Datentyp (UDT), wenn Sie einen SDK generieren.

In diesem Modell gilt:

1. Das $schema Objekt stellt einen gültigen JSON Schemaversionsbezeichner dar. Dieses Schema ist der JSON Schemaentwurf v4.

2. Das Objekt title ist eine lesbare Kennung des Modells. Dieser Titel ist PetStoreModel.

3. Das required-Validierungsschlüsselwort erfordert type und price für die grundlegende Anforderungsvalidierung.

4. Die properties des Modells sind id, type und price. Jedes Objekt hat Eigenschaften, die im Modell beschrieben werden.

5. Das Objekt type kann nur die Werte dog, cat oder fish haben.

6. Das Objekt price ist eine Zahl und auf einen minimum-Wert von 25 und einen maximum-Wert von 500 beschränkt.

PetStore Modell

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 }

In diesem Modell gilt:

1. In Zeile 2 stellt das $schema Objekt eine gültige JSON Schema-Versions-ID dar. Dieses Schema ist der JSON Schemaentwurf v4.

2. In Zeile 3 ist das Objekt title eine lesbare Kennung des Modells. Dieser Titel ist PetStoreModel.

3. In Zeile 5 erfordert das required Validierungsschlüsselwort type und price für die grundlegende Anforderungsvalidierung.

4. In den Zeilen 6 bis 17 sind die properties des Modells id ,type und price. Jedes Objekt hat Eigenschaften, die im Modell beschrieben werden.

5. In Zeile 12 type kann das Objekt nur die Werte dog, cat oder fish haben.

6. In den Zeilen 14 bis 17  ist das Objekt price eine Zahl und durch einen minimum-Wert von 25 und einen maximum-Wert von 500 eingeschränkt.

Erstellen komplexerer Modelle

Sie können das $ref-Primitiv verwenden, um wiederverwendbare Definitionen für längere Modelle zu erstellen. Sie können beispielsweise eine Definition mit der Bezeichnung Price im definitions-Abschnitt zur Beschreibung des price-Objekts erstellen. Der Wert von $ref ist die Price-Definition.

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

Sie können auch auf ein anderes Modellschema verweisen, das in einer externen Modelldatei definiert ist. Stellen Sie den Wert der $ref-Eigenschaft auf die Position des Modells ein. Im folgenden Beispiel ist das Price Modell im PetStorePrice Modell in definiert APIa1234.

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

Das längere Modell kann auf das PetStorePrice-Modell verweisen.

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

Verwendung von Ausgabedatenmodellen

Wenn Sie Ihre Daten umwandeln, können Sie in der Integrationsantwort ein Nutzlastmodell definieren. Ein Payload-Modell kann verwendet werden, wenn Sie ein SDK generieren. Bei stark typisierten Sprachen wie Java, Objective-C oder Swift entspricht das Objekt einem benutzerdefinierten Datentyp (). UDT APIGateway erstellt ein, UDT wenn Sie ihm beim Generieren ein Datenmodell zur Verfügung stellen. SDK Weitere Informationen zu Datentransformationen finden Sie unter Zuordnungsvorlagen für REST APIs.

Das folgende Beispiel zeigt Ausgabedaten aus einer Integrationsantwort.

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

Das folgende Beispiel ist ein Nutzdatenmodell, das die Ausgabedaten beschreibt.

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

Mit diesem Modell können Sie an aufrufen, SDK um die askingPrice Eigenschaftswerte description und abzurufen, indem Sie die PetStoreOutputModel[i].askingPrice Eigenschaften PetStoreOutputModel[i].description und lesen. Wenn kein Modell bereitgestellt wird, verwendet API Gateway das leere Modell, um ein Standardmodell zu erstellenUDT.

Nächste Schritte

• In diesem Abschnitt finden Sie Ressourcen, die Sie verwenden können, um mehr über die in diesem Thema vorgestellten Konzepte zu erfahren.

  Sie können den Tutorials zur Validierung von Anfragen folgen:

  • Richten Sie die Anforderungsvalidierung mit der API Gateway-Konsole ein

  • Richten Sie die grundlegende Anforderungsvalidierung mit dem ein AWS CLI

  • Richten Sie die grundlegende Anforderungsvalidierung mithilfe einer API Open-Definition ein

• Weitere Informationen zu Datenumwandlungs- und Zuweisungsvorlagen finden Sie unter Zuordnungsvorlagen für REST APIs.

• Sie können auch kompliziertere Datenmodelle sehen. Siehe Beispieldatenmodelle und Zuordnungsvorlagen für API Gateway.