Datenmodelle für REST APIs

In API Gateway definiert ein Modell die Datenstruktur eines Payloads. In API Gateway werden Modelle unter Verwendung des JSON-Schemaentwurfs 4 definiert. Das folgende JSON-Objekt enthält Beispieldaten im Tierhandlungsbeispiel.

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

In diesem Modell gilt:

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 }

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 }

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 der API a1234 definiert.

{
  "$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 Nutzlastmodell 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). API Gateway erstellt eine UDT, wenn Sie ihm bei der Generierung eines SDK ein Datenmodell zur Verfügung stellen. Weitere Informationen zu Datentransformationen finden Sie unter Mapping-Vorlagen für REST APIs.

Im folgenden Beispiel sehen Sie die Ausgabedaten 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
  }
]
}

Im folgenden Beispiel sehen Sie ein Payload-Modell, 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 ein SDK aufrufen, um die Eigenschaftswerte description und askingPrice durch Lesen der Eigenschaften PetStoreOutputModel[i].description und PetStoreOutputModel[i].askingPrice abzurufen. Wenn kein Modell zur Verfügung gestellt wird, verwendet API Gateway das leere Modell zur Erstellung einer Standard-UDT.

Nächste Schritte