Tutorial: REST-API als Amazon Kinesis-Proxy erstellen - Amazon API Gateway
Erstellen Sie eine IAM-Rolle und Richtlinien für den Zugriff der API auf KinesisEine API als Kinesis-Proxy erstellenStreams in Kinesis auflistenStream in Kinesis erstellen, beschreiben und löschenDatensätze aus einem Stream in Kinesis abrufen und Datensätze zu einem Stream hinzufügen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Tutorial: REST-API als Amazon Kinesis-Proxy erstellen

Auf dieser Seite wird beschrieben, wie eine REST-API durch Integration des AWS-Typs für den Zugriff auf Kinesis erstellt und konfiguriert wird.

Anmerkung

Um Ihre API Gateway-API in Kinesis zu integrieren, müssen Sie eine Region wählen, in der sowohl das API Gateway als auch die Kinesis-Services verfügbar sind. Informationen zur Verfügbarkeit der Regionen finden Sie unter Service-Endpunkte und Kontingente.

Zur Veranschaulichung erstellen wir eine Beispiel-API, so dass ein Client die folgenden Aufgaben ausführen kann:

  1. Verfügbare Streams des Benutzers in Kinesis auflisten

  2. Erstellen, Beschreiben oder Löschen eines bestimmten Streams

  3. Lesen von Datensätzen aus einem oder Schreiben von Datensätzen in einen bestimmten Stream

Für die Ausführung der obigen Aufgaben stellt die API Methoden für verschiedene Ressourcen bereit, um Folgendes aufzurufen:

  1. Die ListStreams-Aktion in Kinesis

  2. Die Aktion CreateStream, DescribeStream oder DeleteStream

  3. Die GetRecords- oder PutRecords-Aktion (einschließlich PutRecord) in Kinesis

Genauer gesagt wird die API wie folgt erstellt:

  • Sie stellen eine HTTP GET-Methode für die /streams-Ressource der API zur Verfügung und integrieren die Methode in die ListStreams-Aktion in Kinesis, um die Streams im Konto des Aufrufers aufzulisten.

  • Sie stellen eine HTTP POST-Methode für die /streams/{stream-name}-Ressource der API bereit und integrieren die Methode in die CreateStream-Aktion in Kinesis, um einen benannten Stream im Konto des Aufrufers zu erstellen.

  • Sie stellen eine HTTP GET-Methode für die /streams/{stream-name}-Ressource der API zur Verfügung und integrieren die Methode in die DescribeStream-Aktion in Kinesis, um einen benannten Stream im Konto des Aufrufers zu beschreiben.

  • Sie stellen eine HTTP DELETE-Methode für die /streams/{stream-name}-Ressource der API bereit und integrieren die Methode in die DeleteStream-Aktion in Kinesis, um einen Stream im Konto des Aufrufers zu löschen.

  • Sie setzen eine HTTP PUT-Methode für die /streams/{stream-name}/record-Ressource der API ein und integrieren die Methode in der PutRecord-Aktion in Amazon Kinesis. Dadurch kann der Client einen einzelnen Datensatz zum benannten Stream hinzufügen.

  • Sie nutzen eine HTTP PUT-Methode für die /streams/{stream-name}/records-Ressource der API und integrieren die Methode in der PutRecords-Aktion in Amazon Kinesis. Dadurch kann der Client eine Liste mit Datensätzen zum benannten Stream hinzufügen.

  • Sie stellen eine HTTP GET-Methode für die /streams/{stream-name}/records-Ressource der API bereit und integrieren die Methode in der GetRecords-Aktion in Amazon Kinesis. Auf diese Weise kann der Client Datensätze im benannten Stream mit einem angegebenen gemeinsamen Iterator auflisten. Ein gemeinsamer Iterator gibt die gemeinsame Position an, ab der Datensätze sequenziell ausgelesen werden sollen.

  • Sie stellen eine HTTP GET-Methode für die /streams/{stream-name}/sharditerator-Ressource der API zur Verfügung und integrieren die Methode in der GetShardIterator-Aktion in Amazon Kinesis. Diese Hilfsmethode muss der ListStreams-Aktion in Kinesis zur Verfügung gestellt werden.

Sie können die hier vorgestellten Anweisungen auf andere Kinesis-Aktionen anwenden. Die vollständige Liste der Kinesis-Aktionen finden Sie unter Amazon Kinesis API-Referenz.

Anstatt die API Gateway-Konsole zur Erstellung der Beispiel-API zu verwenden, können Sie die Beispiel-API mit der API Gateway Import API in API Gateway importieren. Informationen zur Verwendung der Import-API finden Sie unter REST-APIs mit OpenAPI in API Gateway erstellen.

Erstellen Sie eine IAM-Rolle und Richtlinien für den Zugriff der API auf Kinesis

Einer IAM-Rolle müssen entsprechende IAM-Richtlinien zugeordnet sein, damit die API Kinesis-Aktionen aufrufen kann. In dieser Übung erstellen Sie eine neue IAM-Rolle.

Erstellen der Ausführungsrolle für den AWS-Service-Proxy

  1. Melden Sie sich bei der AWS Management Console an, und öffnen Sie die IAM-Konsole unter https://console.aws.amazon.com/iam/.

  2. Wählen Sie Roles.

  3. Wählen Sie Create role aus.

  4. Wählen Sie unter Typ der vertrauenswürdigen Entität auswählen die Option AWS-Service und anschließend API Gateway und Erlaubt API Gateway, Protokolle an CloudWatch Logs zu senden aus.

  5. Klicken Sie auf Weiter und dann erneut auf Weiter.

  6. Geben Sie für Role name (Rollenname) den Namen APIGatewayKinesisProxyPolicy ein und klicken Sie auf Create role (Rolle erstellen).

  7. Wählen Sie in der Liste Roles die Rolle aus, die Sie gerade erstellt haben. Möglicherweise müssen Sie scrollen oder die Rolle über die Suchleiste finden.

  8. Wählen Sie für die ausgewählte Rolle die Registerkarte Berechtigungen hinzufügen aus.

  9. Wählen Sie in der Dropdown-Liste Berechtigungen anfügen aus.

  10. Geben Sie im Suchfeld AmazonKinesisFullAccess ein und wählen Sie Berechtigungen hinzufügen aus.

    Anmerkung

    Dieses Tutorial verwendet der Einfachheit halber eine verwaltete Richtlinie. Als Best Practice sollten Sie Ihre eigene IAM-Richtlinie erstellen, um die erforderlichen Mindestberechtigungen zu gewähren.

  11. Notieren Sie sich den neu erstellten Rollen-ARN, Sie werden ihn später brauchen.

Eine API als Kinesis-Proxy erstellen

Führen Sie die folgenden Schritte aus, um die API in der API Gateway-Konsole zu erstellen.

So erstellen Sie eine API als AWS-Service-Proxy für Kinesis:

  1. Melden Sie sich bei der API Gateway-Konsole unter https://console.aws.amazon.com/apigateway an.

  2. Wenn Sie API Gateway zum ersten Mal verwenden, sehen Sie eine Seite, die Sie mit den Funktionen des Service vertraut macht. Wählen Sie unter REST-API die Option Build (Erstellen) aus. Wenn das Popup-Fenster Create Example API (Beispiel-API erstellen) angezeigt wird, klicken Sie auf OK.

    Wenn Sie API Gateway nicht zum ersten Mal verwenden, wählen Sie Create API (API erstellen). Wählen Sie unter REST-API die Option Build (Erstellen) aus.

  3. Klicken Sie auf New API (Neue API).

  4. Geben Sie unter API name (API-Name) KinesisProxy ein. Belassen Sie alle Standardwerte für die anderen Felder unverändert.

  5. (Optional) Geben Sie unter Description (Beschreibung) eine Beschreibung ein.

  6. Wählen Sie unter IP-Adresstyp die Option IPv4 aus.

  7. Wählen Sie Create API (API erstellen) aus.

Nachdem die API erstellt wurde, zeigt die API Gateway-Konsole die Seite Resources (Ressourcen) an, die nur die Root-Ressource (/) der API enthält.

Streams in Kinesis auflisten

Kinesis unterstützt die Aktion ListStreams mit dem folgenden REST-API-Aufruf: 

POST /?Action=ListStreams HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
        
{
   ...
}

In der oben gezeigten REST-API-Anforderung wird die Aktion im Action-Abfrageparameter angegeben. Alternativ können Sie stattdessen die Aktion in einer X-Amz-Target-Kopfzeile angeben:

POST / HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
X-Amz-Target: Kinesis_20131202.ListStreams        
{
   ...
}

In diesem Tutorial verwenden wir den Abfrageparameter, um Aktionen festzulegen.

Um eine Kinesis-Aktion in der API bereitzustellen, fügen Sie eine /streams-Ressource zum Stamm der API hinzu. Richten Sie dann eine GET-Methode für die Ressource ein und integrieren Sie die Methode mit der ListStreams-Aktion von Kinesis.

Das folgende Verfahren beschreibt die Auflistung von Kinesis-Streams mit Hilfe der API Gateway-Konsole.

So listen Sie Kinesis-Streams über die API Gateway-Konsole auf:

  1. Wählen Sie die /-Ressource aus und klicken Sie dann auf Ressource erstellen.

  2. Geben Sie für Resource name (Ressourcenname) streams ein.

  3. CORS (Cross Origin Resource Sharing) bleibt ausgeschaltet.

  4. Wählen Sie Create Resource (Ressource erstellen) aus.

  5. Wählen Sie die /streams-Ressource aus, klicken Sie auf Methode erstellen und gehen Sie dann wie folgt vor:

    1. Wählen Sie als Methodentyp die Option GET (Abrufen) aus.

      Anmerkung

      Das HTTP-Verb für eine Methode, die von einem Client aufgerufen wird, kann sich von dem HTTP-Verb unterscheiden, das für eine Integration für das Backend erforderlich ist. Hier wählen wir GET aus, da das Auflisten von Streams intuitiv ein READ-Vorgang ist.

    2. Als Integrationstyp wählen Sie AWS-Dienst aus.

    3. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

    4. Für AWS-Service wählen Sie Kinesis aus.

    5. Lassen Sie die AWS-Subdomain leer.

    6. Wählen Sie in HTTP method POST.

      Anmerkung

      Wir haben hier POST gewählt, weil Kinesis erfordert, dass die Aktion ListStreams mit aufgerufen wird.

    7. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

    8. Für Aktionsname geben Sie ListStreams ein.

    9. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

    10. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

    11. Wählen Sie Methode erstellen aus.

  6. Klicken Sie auf der Registerkarte Integrationsanfrage unter Einstellungen für Integrationsanfragen auf Bearbeiten.

  7. Wählen Sie für Anforderungstext-Pass-Through die Einstellung Wenn keine Vorlagen definiert sind (empfohlen) aus.

  8. Klicken Sie auf URL-Abfragezeichenfolgen-Parameter und gehen Sie dann wie folgt vor:

    1. Klicken Sie auf Parameter Anforderungsheader hinzufügen.

    2. Geben Sie als Name die Zeichenfolge „Content-Type“ ein.

    3. Geben Sie für Zugeordnet von 'application/x-amz-json-1.1' ein.

    Wir verwenden eine Zuweisung für den Anfrageparameter, um den Content-Type-Header auf den statischen Wert 'application/x-amz-json-1.1' einzustellen und damit Kinesis mitzuteilen, dass die Eingabe in einer bestimmten JSON-Version erfolgt.

  9. Wählen Sie Mapping-Vorlagen und dann Mapping-Vorlage hinzufügen aus und gehen Sie dann wie folgt vor:

    1. Geben Sie für Inhaltstyp application/json ein.

    2. Geben Sie für Vorlage {} ein.

    3. Wählen Sie Speichern aus.

    Die ListStreams-Anfrage verwendet eine Nutzlast mit dem folgenden JSON-Format: 

    
{
    "ExclusiveStartStreamName": "string",
    "Limit": number
}

    Die Eigenschaften sind jedoch optional. Wir haben uns für eine leere JSON-Nutzlast entschieden, um die Standardwerte zu verwenden.

  10. Testen Sie die GET-Methode für die /streams-Ressource zum Aufrufen der ListStreams-Aktion in Kinesis:

    Wählen Sie die Registerkarte Test. Möglicherweise müssen Sie die rechte Pfeiltaste wählen, um die Registerkarte anzuzeigen.

    Klicken Sie auf Test, um Ihre Methode zu testen.

    Wenn Sie bereits zwei Streams mit den Namen „myStream“ und „yourStream“ in Kinesis erstellt haben, gibt der Test im Erfolgsfall die Antwort „200 OK“ mit der folgenden Nutzlast zurück: 

    
{
     "HasMoreStreams": false,
     "StreamNames": [
         "myStream",
         "yourStream"
     ]
}

Stream in Kinesis erstellen, beschreiben und löschen

Das Erstellen, Beschreiben und Löschen eines Streams in Kinesis umfasst jeweils die folgenden Kinesis REST-API-Anfragen: 


POST /?Action=CreateStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "ShardCount": number,
    "StreamName": "string"
}                               
            

POST /?Action=DescribeStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "StreamName": "string"
}                                          
            

POST /?Action=DeleteStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "StreamName":"string"
}

Sie können die API so erstellen, dass sie die erforderliche Eingabe als JSON-Nutzlast der Methodenanforderung akzeptiert und die Nutzlast bis zur Integrationsanforderung weiterleitet. Die API wird jedoch geringfügig abgewandelt, um weitere Beispiele für die Datenzuweisung zwischen Methoden- und Integrationsanforderungen sowie Methoden- und Integrationsantworten bereitzustellen.

Sie nutzen die HTTP-Methoden GET, POST und Delete für eine Ressource, die den Namen Stream erhält. Sie verwenden die Pfadvariable {stream-name} als Platzhalter für die Stream-Ressource und integrieren diese API-Methoden in die entsprechenden DescribeStream-, CreateStream- und DeleteStream-Aktionen von Kinesis. Wir benötigen, dass der Client andere Eingabedaten als Header, Abfrageparameter oder Nutzdaten einer Methodenanforderung weitergibt. Wir stellen Mapping-Vorlagen zur Verfügung, um die Daten in die erforderliche Nutzlast der Integrationsanforderung zu transformieren.

Erstellen einer {Stream-name}-Ressource

  1. Wählen Sie die Ressource /streams aus und klicken Sie dann auf Ressource erstellen.

  2. Die Proxy-Ressource bleibt ausgeschaltet.

  3. Wählen Sie für Ressourcenpfad /streams aus.

  4. Geben Sie für Resource name (Ressourcenname) {stream-name} ein.

  5. CORS (Cross Origin Resource Sharing) bleibt ausgeschaltet.

  6. Wählen Sie Create Resource (Ressource erstellen) aus.

So konfigurieren und testen Sie die GET-Methode für eine Stream-Ressource

  1. Wählen Sie die Ressource /{stream-name} aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie als Methodentyp die Option GET (Abrufen) aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie DescribeStream ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Wählen Sie Methode erstellen aus.

  13. Fügen Sie im Abschnitt Integrationsanfrage die folgenden Parameter für URL-Anforderungsheader hinzu:

    Content-Type: 'x-amz-json-1.1'

    Die Aufgabe folgt demselben Verfahren, um die Zuweisung des Anforderungsparameters für die Methode GET /streams einzurichten.

  14. Fügen Sie die folgende Textzuweisungsvorlage hinzu, um Daten der Methodenanforderung GET /streams/{stream-name} der Integrationsanforderung POST /?Action=DescribeStream zuzuweisen:

    {
    "StreamName": "$input.params('stream-name')"
}

    Diese Zuweisungsvorlage generiert die erforderliche Nutzlast der Integrationsanforderung für die Aktion DescribeStream von Kinesis aufgrund des Pfadparameterwerts stream-name der Methodenanforderung.

  15. Klicken Sie auf die Registerkarte Test, um die GET /stream/{stream-name}-Methode zum Aufrufen der DescribeStream-Aktion in Kinesis zu testen.

  16. Geben Sie unter Stream-Name den Namen eines vorhandenen Kinesis-Streams für Pfad ein.

  17. Wählen Sie Test aus. Wenn der Test erfolgreich ist, wird die Antwort "200 OK" mit einer Nutzlast ähnlich der folgenden zurückgegeben: 

    {
  "StreamDescription": {
    "HasMoreShards": false,
    "RetentionPeriodHours": 24,
    "Shards": [
      {
        "HashKeyRange": {
          "EndingHashKey": "68056473384187692692674921486353642290",
          "StartingHashKey": "0"
        },
        "SequenceNumberRange": {
          "StartingSequenceNumber": "49559266461454070523309915164834022007924120923395850242"
        },
        "ShardId": "shardId-000000000000"
      },
      ...
      {
        "HashKeyRange": {
          "EndingHashKey": "340282366920938463463374607431768211455",
          "StartingHashKey": "272225893536750770770699685945414569164"
        },
        "SequenceNumberRange": {
          "StartingSequenceNumber": "49559266461543273504104037657400164881014714369419771970"
        },
        "ShardId": "shardId-000000000004"
      }
    ],
    "StreamARN": "arn:aws:kinesis:us-east-1:12345678901:stream/myStream",
    "StreamName": "myStream",
    "StreamStatus": "ACTIVE"
  }
}

    Nach der Bereitstellung der API können Sie eine REST-Anforderung für diese API-Methode erstellen: 

    
GET https://your-api-id.execute-api.region.amazonaws.com/stage/streams/myStream HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z
So konfigurieren und testen Sie die POST-Methode für eine Stream-Ressource

  1. Wählen Sie die Ressource /{stream-name} aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie unter Method type (Methodentyp) die Option POST aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie CreateStream ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Wählen Sie Methode erstellen aus.

  13. Fügen Sie im Abschnitt Integrationsanfrage die folgenden Parameter für URL-Anforderungsheader hinzu:

    Content-Type: 'x-amz-json-1.1'

    Die Aufgabe folgt demselben Verfahren, um die Zuweisung des Anforderungsparameters für die Methode GET /streams einzurichten.

  14. Fügen Sie die folgende Textzuweisungsvorlage hinzu, um Daten der Methodenanforderung POST /streams/{stream-name} der Integrationsanforderung POST /?Action=CreateStream zuzuweisen: 

    {
    "ShardCount": #if($input.path('$.ShardCount') == '') 5 #else $input.path('$.ShardCount') #end,
    "StreamName": "$input.params('stream-name')"
}

    In der vorhergehenden Zuweisungsvorlage legen wir ShardCount auf einen festen Wert von 5 fest, wenn vom Client kein Wert in der Nutzlast der Methodenanforderung angegeben wird.

  15. Klicken Sie auf die Registerkarte Test, um die POST /stream/{stream-name}-Methode zum Aufrufen der CreateStream-Aktion in Kinesis zu testen.

  16. Geben Sie für Path unter Stream-Name den Namen eines neuen Kinesis-Streams für Pfad ein.

  17. Wählen Sie Test aus. Wenn der Test erfolgreich ist, wird die Antwort "200 OK" ohne Daten zurückgegeben.

    Nach der Bereitstellung der API können Sie auch eine REST-API-Anfrage im Hinblick auf die POST-Methode für eine Stream-Ressource erstellen, um die CreateStream-Aktion in Amazon Kinesis aufzurufen: 

    
POST https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z

{ 
    "ShardCount": 5
}
Konfigurieren und Testen der DELETE-Methode für eine Stream-Ressource

  1. Wählen Sie die Ressource /{stream-name} aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie als Methodentyp LÖSCHEN aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie DeleteStream ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Wählen Sie Methode erstellen aus.

  13. Fügen Sie im Abschnitt Integrationsanfrage die folgenden Parameter für URL-Anforderungsheader hinzu:

    Content-Type: 'x-amz-json-1.1'

    Die Aufgabe folgt demselben Verfahren, um die Zuweisung des Anforderungsparameters für die Methode GET /streams einzurichten.

  14. Fügen Sie die folgende Textzuweisungsvorlage hinzu, um Daten der Methodenanforderung DELETE /streams/{stream-name} der entsprechenden Integrationsanforderung POST /?Action=DeleteStream zuzuweisen: 

    {
    "StreamName": "$input.params('stream-name')"
}

    Diese Zuweisungsvorlage generiert die erforderliche Eingabe für die Aktion DELETE /streams/{stream-name} aus dem vom Client bereitgestellten URL-Pfad stream-name.

  15. Klicken Sie auf die Registerkarte Test, um die DELETE /stream/{stream-name}-Methode zum Aufrufen der DeleteStream-Aktion in Kinesis zu testen.

  16. Geben Sie unter Stream-Name den Namen eines vorhandenen Kinesis-Streams für Pfad ein.

  17. Wählen Sie Test aus. Wenn der Test erfolgreich ist, wird die Antwort "200 OK" ohne Daten zurückgegeben.

    Nach der Bereitstellung der API können Sie auch die folgende REST-API-Anfrage im Hinblick auf die DELETE-Methode für die Stream-Ressource erstellen, um die DeleteStream-Aktion in Amazon Kinesis aufzurufen: 

    
DELETE https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z

{}

Datensätze aus einem Stream in Kinesis abrufen und Datensätze zu einem Stream hinzufügen

Nachdem Sie einen Stream in Kinesis erstellt haben, können Sie dem Stream Datensätze hinzufügen und die Daten aus dem Stream lesen. Beim Hinzufügen von Datensätzen wird die PutRecords- oder die PutRecord-Aktion in Amazon Kinesis aufgerufen. Erstere fügt dem Stream mehrere Datensätze hinzu, letztere hingegen einen einzigen Datensatz. 


POST /?Action=PutRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "Records": [
        {
            "Data": blob,
            "ExplicitHashKey": "string",
            "PartitionKey": "string"
        }
    ],
    "StreamName": "string"
}

oder


POST /?Action=PutRecord HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "Data": blob,
    "ExplicitHashKey": "string",
    "PartitionKey": "string",
    "SequenceNumberForOrdering": "string",
    "StreamName": "string"
}

Hier identifiziert StreamName den Zieldatenstrom zum Hinzufügen von Datensätzen. StreamName, Data, und PartitionKey sind erforderliche Eingabedaten. In diesem Beispiel werden die Standardwerte für alle optionalen Eingabedaten verwendet. Es erfolgt keine explizite Angabe entsprechender Werte in der Eingabe für die Methodenanforderung.

Das Lesen von Daten in Kinesis läuft über den Aufruf der Aktion GetRecords: 

POST /?Action=GetRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "ShardIterator": "string",
    "Limit": number
}

Hier wird der Quell-Stream, von dem die Datensätze abgerufen werden, im erforderlichen ShardIterator-Wert angegeben. Dies wird in der folgenden Kinesis-Aktion zum Abrufen eines gemeinsamen Iterators verdeutlicht:


POST /?Action=GetShardIterator HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
                
{
    "ShardId": "string",
    "ShardIteratorType": "string",
    "StartingSequenceNumber": "string",
    "StreamName": "string"
}

Für die Aktionen GetRecords und PutRecords werden die Methoden GET und PUT entsprechend für eine /records-Ressource bereitgestellt, die einem benannten Stream hinzugefügt wird (/{stream-name}). Ebenso wird die PutRecord-Aktion als PUT-Methode für eine /record-Ressource verfügbar gemacht.

Da die Aktion GetRecords als Eingabe einen ShardIterator-Wert verwendet, der durch Aufrufen der Hilfsaktion GetShardIterator gewonnen wurde, stellen Sie eine GET-Hilfsmethode für eine ShardIterator-Ressource bereit (/sharditerator).

So erstellen Sie die Ressourcen /record, /records und /sharditerator

  1. Wählen Sie die Ressource /{stream-name} aus und klicken Sie dann auf Ressource erstellen.

  2. Die Proxy-Ressource bleibt ausgeschaltet.

  3. Wählen Sie für Ressourcenpfad /{stream-name} aus.

  4. Geben Sie für Resource name (Ressourcenname) record ein.

  5. CORS (Cross Origin Resource Sharing) bleibt ausgeschaltet.

  6. Wählen Sie Create Resource (Ressource erstellen) aus.

  7. Wiederholen Sie die Schritte oben, um eine /records- und eine /sharditerator-Ressource zu erstellen. Die endgültige API sollte wie folgt aussehen:

    Erstellen Sie die Methoden Records:GET|PUT|PUT|GET für die API.

In den folgenden vier Verfahren wird beschrieben, wie Sie die jeweiligen Methoden einrichten, Daten aus den Methodenanforderungen den Integrationsanforderungen zuweisen und die Methoden testen.

Einrichten und Testen der PUT /streams/{stream-name}/record-Methode zum Aufruf von PutRecord in Kinesis:

  1. Wählen Sie /record aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie unter Methodentyp PUT aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie PutRecord ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Wählen Sie Methode erstellen aus.

  13. Fügen Sie im Abschnitt Integrationsanfrage die folgenden Parameter für URL-Anforderungsheader hinzu:

    Content-Type: 'x-amz-json-1.1'

    Die Aufgabe folgt demselben Verfahren, um die Zuweisung des Anforderungsparameters für die Methode GET /streams einzurichten.

  14. Fügen Sie die folgende Textzuweisungsvorlage hinzu, um Daten der Methodenanforderung PUT /streams/{stream-name}/record der entsprechenden Integrationsanforderung POST /?Action=PutRecord zuzuweisen: 

    {
    "StreamName": "$input.params('stream-name')",
    "Data": "$util.base64Encode($input.json('$.Data'))",
    "PartitionKey": "$input.path('$.PartitionKey')"
}

    In dieser Zuweisungsvorlage wird davon ausgegangen, dass die Nutzlast der Methodenanforderung folgendes Format aufweist: 

    {
   "Data": "some data",
   "PartitionKey": "some key"
}

    Diese Daten können mithilfe des folgenden JSON-Schemas modelliert werden:

    {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PutRecord proxy single-record payload",
  "type": "object",
  "properties": {
      "Data": { "type": "string" },
      "PartitionKey": { "type": "string" }
  }
}

    Sie können ein Modell mit diesem Schema erstellen und es verwenden, um die Generierung der Zuweisungsvorlage zu vereinfachen. Sie können eine Zuweisungsvorlage jedoch auch ohne ein Modell erstellen.

  15. Testen Sie die Methode PUT /streams/{stream-name}/record, indem Sie die Pfadvariable stream-name auf den Namen eines vorhandenen Streams festlegen, eine Nutzlast im erforderlichen Format bereitstellen und die Methodenanforderung dann senden. Das Ergebnis im Erfolgsfall ist die Antwort 200 OK mit einer Nutzlast in folgendem Format: 

    
{
  "SequenceNumber": "49559409944537880850133345460169886593573102115167928386",
  "ShardId": "shardId-000000000004"
}
So richten Sie die PUT /streams/{stream-name}/records-Methode zum Aufruf von PutRecords in Kinesis ein und testen sie:

  1. Wählen Sie die Ressource /records aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie unter Methodentyp PUT aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie PutRecords ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Wählen Sie Methode erstellen aus.

  13. Fügen Sie im Abschnitt Integrationsanfrage die folgenden Parameter für URL-Anforderungsheader hinzu:

    Content-Type: 'x-amz-json-1.1'

    Die Aufgabe folgt demselben Verfahren, um die Zuweisung des Anforderungsparameters für die Methode GET /streams einzurichten.

  14. Fügen Sie die folgende Zuweisungsvorlage hinzu, um Daten der PUT /streams/{stream-name}/records-Methodenanforderung der entsprechenden POST /?Action=PutRecords-Integrationsanforderung zuzuweisen: 

    {
    "StreamName": "$input.params('stream-name')",
    "Records": [
       #foreach($elem in $input.path('$.records'))
          {
            "Data": "$util.base64Encode($elem.data)",
            "PartitionKey": "$elem.partition-key"
          }#if($foreach.hasNext),#end
        #end
    ]
}

    In dieser Zuweisungsvorlage wird davon ausgegangen, dass die Nutzlast der Methodenanforderung anhand des folgenden JSON-Schemas modelliert werden kann:

    {
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "PutRecords proxy payload data",
  "type": "object",
  "properties": {
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "data": { "type": "string" },
          "partition-key": { "type": "string" }
        }
      }
    }
  }
}

    Sie können ein Modell mit diesem Schema erstellen und es verwenden, um die Generierung der Zuweisungsvorlage zu vereinfachen. Sie können eine Zuweisungsvorlage jedoch auch ohne ein Modell erstellen.

    In diesem Tutorial haben wir zwei geringfügig unterschiedliche Nutzdatenformate verwendet, um zu veranschaulichen, dass ein API-Entwickler je nach Bedarf das Backend-Datenformat für den Client offenlegen oder gegenüber dem Client verbergen kann. Eines dieser Formate ist für die Methode PUT /streams/{stream-name}/records bestimmt (oben). Ein anderes Format wird für die Methode PUT /streams/{stream-name}/record (im vorherigen Verfahren) verwendet. In einer Produktionsumgebung sollten beide Formate konsistent bleiben.

  15. Testen Sie die Methode PUT /streams/{stream-name}/records, indem Sie die Pfadvariable stream-name auf einen vorhandenen Stream festlegen, die folgende Nutzlast bereitstellen und die Methodenanforderung senden. 

    
{
    "records": [
        {
            "data": "some data",
            "partition-key": "some key"
        },
        {
            "data": "some other data",
            "partition-key": "some key"
        }
    ]
}

    Das Ergebnis im Erfolgsfall ist die Antwort "200 OK" mit einer Nutzlast, die der folgenden Ausgabe ähnelt: 

    {
  "FailedRecordCount": 0,
  "Records": [
    {
      "SequenceNumber": "49559409944537880850133345460167468741933742152373764162",
      "ShardId": "shardId-000000000004"
    },
    {
      "SequenceNumber": "49559409944537880850133345460168677667753356781548470338",
      "ShardId": "shardId-000000000004"
    }
  ]
}
Richten Sie die GET /streams/{stream-name}/sharditerator-Methode ein und testen Sie sie, indem Sie GetShardIterator in Kinesis aufrufen

Die Methode GET /streams/{stream-name}/sharditerator ist eine Hilfsmethode, um einen erforderlichen gemeinsamen Iterator vor dem Aufrufen der Methode GET /streams/{stream-name}/records zu beschaffen.

  1. Wählen Sie die Ressource /sharditerator aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie als Methodentyp die Option GET (Abrufen) aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie GetShardIterator ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Klicken Sie auf Parameter für URL-Abfragezeichenfolgen.

    Die GetShardIterator-Aktion erfordert die Eingabe eines ShardId-Werts. Zur Weitergabe eines vom Client bereitgestellten ShardId-Werts wird der Methodenanforderung ein shard-id-Abfrageparameter wie nachfolgend dargestellt hinzugefügt:

  13. Wählen Sie Abfragezeichenfolge hinzufügen aus.

  14. Geben Sie als Name die Zeichenfolge „shard-id“ ein.

  15. Lassen Sie die Optionen Required (Obligatorisch) and Caching (Cache) deaktiviert.

  16. Wählen Sie Methode erstellen aus.

  17. Fügen Sie im Abschnitt Integrationsanforderung die folgende Zuweisungsvorlage hinzu, um die erforderlichen Eingaben (ShardId und StreamName) für die GetShardIterator-Aktion aus den Parametern shard-id und stream-name der Methodenanforderung zu generieren. Durch die Zuweisungsvorlage wird außerdem ShardIteratorType auf die Standardeinstellung TRIM_HORIZON festgelegt.

    {
    "ShardId": "$input.params('shard-id')",
    "ShardIteratorType": "TRIM_HORIZON",
    "StreamName": "$input.params('stream-name')"
}

  18. Verwenden Sie die Option Test in der Amazon API Gateway-Konsole, geben Sie einen vorhandenen Stream-Namen als Wert der Variablen stream-name Path ein, setzen Sie die shard-id Query string auf einen vorhandenen ShardId-Wert (z. B. shard-000000000004) und wählen Sie Test.

    Im Erfolgsfall sieht die Ausgabe der Antwortnutzlast folgendermaßen oder ähnlich aus: 

    {
  "ShardIterator": "AAAAAAAAAAFYVN3VlFy..."
}

    Notieren Sie sich den Wert für ShardIterator. Sie benötigen ihn, um Datensätze aus einem Stream abzurufen.

So konfigurieren und testen Sie die GET /streams/{stream-name}/records-Methode zum Aufrufen der GetRecords-Aktion in Kinesis:

  1. Wählen Sie die Ressource /records aus und klicken Sie dann auf Methode erstellen.

  2. Wählen Sie als Methodentyp die Option GET (Abrufen) aus.

  3. Als Integrationstyp wählen Sie AWS-Dienst aus.

  4. Für AWS-Region wählen Sie den AWS-Region aus, wo Sie Ihren Kinesis-Stream erstellt haben.

  5. Für AWS-Service wählen Sie Kinesis aus.

  6. Lassen Sie die AWS-Subdomain leer.

  7. Wählen Sie in HTTP method POST.

  8. Für Aktionstyp wählen Sie Aktionsname verwenden aus.

  9. Für Aktionsname geben Sie GetRecords ein.

  10. Für Ausführungsrolle geben Sie den ARN Ihrer Ausführungsrolle ein.

  11. Die Voreinstellung unter Passthrough für Content-Handling bleibt unverändert.

  12. Wählen Sie HTTP-Anforderungs-Headers aus.

    Die GetRecords-Aktion erfordert die Eingabe eines ShardIterator-Werts. Für eine Weitergabe eines vom Client bereitgestellten ShardIterator-Werts muss der Methodenanforderung ein Shard-Iterator-Header-Parameter hinzugefügt werden.

  13. Wählen Sie Add header.

  14. Geben Sie als Name die Zeichenfolge „Shard-Iterator“ ein.

  15. Lassen Sie die Optionen Required (Obligatorisch) and Caching (Cache) deaktiviert.

  16. Wählen Sie Methode erstellen aus.

  17. Fügen Sie die folgende Textzuweisungsvorlage im Abschnitt Integrationsanforderung hinzu, um den Shard-Iterator-Header-Parameterwert dem ShardIterator-Eigenschaftswert der JSON-Nutzlast für die GetRecords-Aktion in Kinesis zuzuweisen. 

    {
    "ShardIterator": "$input.params('Shard-Iterator')"
}

  18. Mithilfe der Option Test in der Amazon-API-Gateway-Konsole geben Sie einen vorhandenen Stream-Namen als Wert der Variablen stream-name-Pfad ein, setzen den Shard-Iterator-Header auf den ShardIterator-Wert aus dem Testdurchlauf der GET /streams/{stream-name}/sharditerator-Methode (oben) und klicken dann auf Test.

    Im Erfolgsfall sieht die Ausgabe der Antwortnutzlast folgendermaßen oder ähnlich aus: 

    {
  "MillisBehindLatest": 0,
  "NextShardIterator": "AAAAAAAAAAF...",
  "Records": [ ... ]
}