Datenmodelle für REST-APIs - Amazon API Gateway
Erstellen komplexerer ModelleVerwendung von AusgabedatenmodellenNächste Schritte

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:

  • Verwenden der grundlegenden Anforderungsvalidierung.

  • Erstellen von Zuweisungsvorlagen für die Datentransformation.

  • Erstellen eines benutzerdefinierten Datentyps (UDT), wenn Sie ein SDK generieren.

Beispiel eines JSON-Datenmodells für die PetStore-API.

In diesem Modell gilt:

  1. Das Objekt $schema stellt eine gültige JSON-Schema-Versionskennung 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.

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 Objekt $schema eine gültige JSON-Schema-Versionskennung 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 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 Zuweisungsvorlagen 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