Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Tutorial: creazione di un'API REST come un proxy Amazon Kinesis
In questa pagina viene descritto come creare e configurare un'API REST con un'integrazione di tipo `AWS` per accedere a Kinesis.
**Nota**
Per integrare l'API di API Gateway con Kinesis, devi scegliere una regione in cui i servizi API Gateway e Kinesis siano entrambi disponibili. Per la disponibilità della regione, vedere [Endpoint e quote del servizio](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html).
Per scopi illustrativi, creeremo un'API di esempio per permettere a un client di eseguire le operazioni seguenti:
1. Elencare i flussi disponibili dell'utente in Kinesis
1. Creare, descrivere o eliminare un flusso specificato.
1. Leggere o scrivere record di dati nel flusso specificato
Per eseguire le attività precedenti, l'API espone metodi in diverse risorse per richiamare, rispettivamente, gli elementi seguenti:
1. L'operazione `ListStreams` in Kinesis
1. Operazione `CreateStream`, `DescribeStream` o `DeleteStream`
1. Operazione `GetRecords` o `PutRecords` (inclusa `PutRecord`) in Kinesis
In particolare, compileremo l'API in questo modo:
+ Esponi un metodo HTTP GET sulla `/streams` risorsa dell'API e integra il metodo con l'[ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html)azione in Kinesis per elencare gli stream nell'account del chiamante.
+ Esponi un metodo HTTP POST sulla `/streams/{stream-name}` risorsa dell'API e integra il metodo con l'[CreateStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_CreateStream.html)azione in Kinesis per creare uno stream denominato nell'account del chiamante.
+ Esponi un metodo HTTP GET sulla `/streams/{stream-name}` risorsa dell'API e integra il metodo con l'[DescribeStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStream.html)azione in Kinesis per descrivere uno stream denominato nell'account del chiamante.
+ Esponi un metodo HTTP DELETE sulla `/streams/{stream-name}` risorsa dell'API e integra il metodo con l'[DeleteStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DeleteStream.html)azione in Kinesis per eliminare uno stream nell'account del chiamante.
+ Esponi un metodo HTTP PUT sulla `/streams/{stream-name}/record` risorsa dell'API e integra il metodo con l'[PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html)azione in Kinesis. In questo modo, il client può aggiungere un singolo record di dati al flusso denominato.
+ Esponi un metodo HTTP PUT sulla `/streams/{stream-name}/records` risorsa dell'API e integra il metodo con l'[PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html)azione in Kinesis. In questo modo, il client può aggiungere un elenco di record di dati al flusso denominato.
+ Esponi un metodo HTTP GET sulla `/streams/{stream-name}/records` risorsa dell'API e integra il metodo con l'[GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html)azione in Kinesis. In questo modo, il client può aggiungere un elenco di record di dati nel flusso denominato, con un'iterazione shard specificata. Un'iterazione shard specifica la posizione dello shard da cui iniziare a leggere i record di dati in sequenza.
+ Esponi un metodo HTTP GET sulla `/streams/{stream-name}/sharditerator` risorsa dell'API e integra il metodo con l'[GetShardIterator](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html)azione in Kinesis. Questo metodo helper deve essere fornito all'operazione `ListStreams` in Kinesis.
Puoi applicare le istruzioni presentate qui ad altre operazioni di Kinesis. Per l'elenco completo delle operazioni di Kinesis, consulta la [documentazione di riferimento delle API di Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/APIReference/Welcome.html).
Invece di usare la console API Gateway per creare l'API di esempio, puoi importare l'API di esempio in API Gateway, usando l'API Gateway di [Importa API](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html). Per informazioni su come usare l'API di importazione, consulta [Sviluppa REST APIs utilizzando OpenAPI in API Gateway](api-gateway-import-api.md).
## Creazione di un ruolo e una policy IAM per l'API per accedere a Kinesis
Per permettere all'API di richiamare le operazioni di Kinesis, devi aver collegato le policy IAM appropriate a un ruolo IAM. In questo passaggio si crea un nuovo ruolo IAM.
**Per creare il ruolo di esecuzione del proxy del AWS servizio**
1. Accedi Console di gestione AWS e apri la console IAM all'indirizzo [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Scegliere **Roles (Ruoli)**.
1. Scegli **Crea ruolo**.
1. Scegli il **AWS servizio** in **Seleziona il tipo di entità affidabile**, quindi seleziona **API Gateway** e seleziona Consenti **a API Gateway di inviare i log ai CloudWatch log**.
1. Scegli **Successivo** e di nuovo **Successivo**.
1. In **Role name (Nome ruolo)** immettere **APIGatewayKinesisProxyPolicy** e quindi selezionare **Create role (Crea ruolo)**.
1. Nell'elenco **Roles (Ruoli)** scegliere il ruolo appena creato. Potrebbe essere necessario scorrere o utilizzare la barra di ricerca per trovare il ruolo.
1. Per il ruolo selezionato, seleziona la scheda **Aggiungi autorizzazioni**.
1. Dall'elenco a discesa scegli **Collega policy**.
1. Nella barra di ricerca inserisci **AmazonKinesisFullAccess** e scegli **Aggiungi autorizzazioni**.
**Nota**
Per semplicità, questo tutorial utilizza una policy gestita. Come best practice, dovresti creare la tua policy IAM per concedere le autorizzazioni minime richieste.
1. Annota l'**ARN del ruolo** appena creato, lo utilizzerai in seguito.
## Creazione di un'API come un proxy Kinesis
Usa la procedura seguente per creare l'API nella console API Gateway.
**Per creare un'API come proxy AWS di servizio per Kinesis**
1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway)
1. Se si utilizza API Gateway per la prima volta, verrà visualizzata una pagina che presenta le caratteristiche del servizio. In **API REST**, scegliere **Crea**. Quando appare il popup **Create Example API (Crea API di esempio)**, scegliere **OK**.
Se non è la prima volta che si utilizza API Gateway, scegliere **Create API (Crea API)**. In **API REST**, scegliere **Crea**.
1. Selezionare **New API (Nuova API)**.
1. Per **API name (Nome API)** immettere **KinesisProxy**. Per tutti gli altri campi mantieni i valori predefiniti.
1. (Facoltativo) In **Descrizione**, immetti una descrizione.
1. Per il tipo di **indirizzo IP**, selezionare. **IPv4**
1. Seleziona **Create API** (Crea API).
Dopo la creazione dell'API, la console API Gateway visualizza la pagina **Resources (Risorse)**, che contiene solo la risorsa root (`/`) dell'API.
## Visualizzazione dell'elenco di flussi in Kinesis
Kinesis supporta l'operazione `ListStreams` con la chiamata API REST seguente:
```
POST /?Action=ListStreams HTTP/1.1
Host: kinesis..
Content-Length:
User-Agent:
Content-Type: application/x-amz-json-1.1
Authorization:
X-Amz-Date:
{
...
}
```
Nella richiesta API REST precedente l'operazione è specificata nel parametro di query `Action`. In alternativa, puoi specificare l'operazione in un'intestazione `X-Amz-Target`:
```
POST / HTTP/1.1
Host: kinesis..
Content-Length:
User-Agent:
Content-Type: application/x-amz-json-1.1
Authorization:
X-Amz-Date:
X-Amz-Target: Kinesis_20131202.ListStreams
{
...
}
```
In questo tutorial useremo il parametro di query per specificare l'operazione.
Per esporre un'operazione di Kinesis nell'API, aggiungi una risorsa `/streams` alla root dell'API. Imposta quindi un metodo `GET` nella risorsa e integra il metodo con l'operazione `ListStreams` di Kinesis.
La procedura seguente descrive come elencare flussi Kinesis tramite la console API Gateway.
**Per elencare i flussi Kinesis utilizzando la console API Gateway**
1. Seleziona la risorsa `/`, quindi scegli **Crea risorsa**.
1. Per **Resource Name (Nome risorsa)** immetti **streams**.
1. Mantieni **CORS (Cross Origin Resource Sharing)** disattivato.
1. Scegli **Crea risorsa**.
1. Scegli la risorsa `/streams` e seleziona **Crea metodo**, quindi procedi come segue:
1. Per **Tipo di metodo** seleziona **GET**.
**Nota**
Il verbo HTTP per un metodo richiamato da un client può differire dal verbo HTTP per un'integrazione richiesta dal back-end. Qui selezioniamo `GET` perché la visualizzazione dell'elenco di flussi è intuitivamente un'operazione READ.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
**Nota**
Qui scegliamo `POST` perché Kinesis richiede che con il metodo venga richiamata l'operazione `ListStreams`.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **ListStreams**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Crea metodo**.
1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**.
1. Per **Richiesta corpo passthrough** scegli **Quando non ci sono modelli definiti (consigliato)**.
1. Scegli **Parametri delle intestazioni delle richieste URL** ed effettua le seguenti operazioni:
1. Scegli **Aggiungi parametro delle intestazioni delle richieste**.
1. In **Nome**, inserisci **Content-Type**.
1. In **Mappato da**, inserire **'application/x-amz-json-1.1'**.
Usiamo la mappatura dei parametri delle richieste per impostare l'intestazione `Content-Type` sul valore statico `'application/x-amz-json-1.1'` per indicare a Kinesis che l'input è una versione specifica di JSON.
1. Scegli **Modelli di mappatura**, quindi seleziona **Aggiungi modello di mappatura** ed effettua le seguenti operazioni:
1. Per **Content-Type** immetti **application/json**.
1. Per **Corpo del modello** immetti **\$1\$1**.
1. Scegli **Save** (Salva).
La [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html#API_ListStreams_RequestSyntax)richiesta richiede un payload nel seguente formato JSON:
```
{
"ExclusiveStartStreamName": "string",
"Limit": number
}
```
Tuttavia, le proprietà sono facoltative. Per usare i valori predefiniti, qui abbiamo optato per un payload JSON vuoto.
1. Testa il metodo GET nella risorsa **/streams** per richiamare l'azione `ListStreams` in Kinesis:
Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
Scegli **Esegui test** per testare il metodo.
Se hai già creato due flussi denominati "myStream" e "yourStream" in Kinesis, il test con esito positivo restituisce una risposta 200 OK che contiene il payload seguente:
```
{
"HasMoreStreams": false,
"StreamNames": [
"myStream",
"yourStream"
]
}
```
## Creazione, descrizione ed eliminazione di un flusso in Kinesis
Per creare, descrivere ed eliminare un flusso in Kinesis è necessario effettuare, rispettivamente, le richieste API REST di Kinesis seguenti:
```
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"
}
```
Puoi compilare l'API in modo da accettare l'input richiesto come payload JSON della richiesta del metodo e passare il payload alla richiesta di integrazione. Tuttavia, per fornire più esempi di mappatura dei dati tra richieste di metodi e di integrazione e le rispettive risposte, creeremo l'API in un modo diverso.
Esponiamo i metodi `GET``POST`, e `Delete` HTTP su una risorsa. to-be-named `Stream` Useremo la variabile di percorso `{stream-name}` come segnaposto della risorsa flusso e integreremo questi metodi API rispettivamente con le operazioni `DescribeStream`, `CreateStream` e `DeleteStream` di Kinesis. Richiederemo che il client passi altri dati di input come intestazioni, parametri di query o payload della richiesta di un metodo. Specificheremo modelli di mappatura per trasformare i dati nel payload della richiesta di integrazione necessario.
**Per creare la risorsa \$1stream-name\$1**
1. Scegli la risorsa **/streams**, quindi seleziona **Crea risorsa**.
1. Mantieni l'opzione **Risorsa proxy** disattivata.
1. Per **Percorso risorsa** seleziona `/streams`.
1. Per **Resource Name (Nome risorsa)** immetti **\$1stream-name\$1**.
1. Mantieni **CORS (Cross Origin Resource Sharing)** disattivato.
1. Scegli **Crea risorsa**.
**Per configurare e testare il metodo GET in una risorsa flusso**
1. Scegli la risorsa **/\$1stream-name\$1**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **DescribeStream**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi i seguenti **parametri delle intestazioni delle richieste URL**:
```
Content-Type: 'x-amz-json-1.1'
```
L'attività segue la stessa procedura usata per configurare la mappatura dei parametri di richiesta per il metodo `GET /streams`.
1. Aggiungi il modello di mappatura del corpo seguente per mappare i dati dalla richiesta del metodo `GET /streams/{stream-name}` alla richiesta di integrazione `POST /?Action=DescribeStream`:
```
{
"StreamName": "$input.params('stream-name')"
}
```
Questo modello di mappatura genera il payload della richiesta di integrazione necessario per l'operazione `DescribeStream` di Kinesis dal valore del parametro di percorso `stream-name` della richiesta del metodo.
1. Per testare il metodo `GET /stream/{stream-name}` per richiamare l'azione `DescribeStream` in Kinesis, scegli la scheda **Test**.
1. Per **Percorso** immetti il nome di un flusso Kinesis esistente in **stream-name**.
1. Scegli **Test (Esegui test)**. Se il test ha esito positivo, viene restituita una risposta 200 OK con un payload simile al seguente:
```
{
"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"
}
}
```
Dopo aver distribuito l'API, puoi effettuare una richiesta REST su questo metodo API:
```
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
```
**Per configurare e testare il metodo POST in una risorsa flusso**
1. Scegli la risorsa **/\$1stream-name\$1**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **POST**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **CreateStream**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi i seguenti **parametri delle intestazioni delle richieste URL**:
```
Content-Type: 'x-amz-json-1.1'
```
L'attività segue la stessa procedura usata per configurare la mappatura dei parametri di richiesta per il metodo `GET /streams`.
1. Aggiungi il modello di mappatura del corpo seguente per mappare i dati dalla richiesta del metodo `POST /streams/{stream-name}` alla richiesta di integrazione `POST /?Action=CreateStream`:
```
{
"ShardCount": #if($input.path('$.ShardCount') == '') 5 #else $input.path('$.ShardCount') #end,
"StreamName": "$input.params('stream-name')"
}
```
Nel modello di mappatura precedente impostiamo `ShardCount` sul valore fisso 5 se il client non specifica alcun valore nel payload della richiesta del metodo.
1. Per testare il metodo `POST /stream/{stream-name}` per richiamare l'azione `CreateStream` in Kinesis, scegli la scheda **Test**.
1. Per **Percorso** immetti il nome di un nuovo flusso Kinesis in **stream-name**.
1. Scegli **Test (Esegui test)**. Se il test ha esito positivo, viene restituita una risposta 200 OK senza dati.
Dopo aver distribuito l'API, puoi anche effettuare una richiesta API REST sul metodo POST in una risorsa flusso per richiamare l'operazione `CreateStream` in Kinesis:
```
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
}
```
**Configurazione e test del metodo DELETE in una risorsa flusso**
1. Scegli la risorsa **/\$1stream-name\$1**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **DELETE**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **DeleteStream**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi i seguenti **parametri delle intestazioni delle richieste URL**:
```
Content-Type: 'x-amz-json-1.1'
```
L'attività segue la stessa procedura usata per configurare la mappatura dei parametri di richiesta per il metodo `GET /streams`.
1. Aggiungi il modello di mappatura del corpo seguente per mappare i dati dalla richiesta del metodo `DELETE /streams/{stream-name}` alla richiesta di integrazione corrispondente di `POST /?Action=DeleteStream`:
```
{
"StreamName": "$input.params('stream-name')"
}
```
Questo modello di mappatura genera l'input richiesto per l'operazione `DELETE /streams/{stream-name}` dal nome di percorso URL fornito dal client `stream-name`.
1. Per testare il metodo `DELETE /stream/{stream-name}` per richiamare l'azione `DeleteStream` in Kinesis, scegli la scheda **Test**.
1. Per **Percorso** immetti il nome di un flusso Kinesis esistente in **stream-name**.
1. Scegli **Test (Esegui test)**. Se il test ha esito positivo, viene restituita una risposta 200 OK senza dati.
Dopo aver distribuito l'API, puoi anche effettuare la richiesta API REST seguente sul metodo DELETE nella risorsa flusso per chiamare l'operazione `DeleteStream` in Kinesis:
```
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
{}
```
## Recupero di record e aggiunta di record in un flusso in Kinesis
Dopo aver creato un flusso in Kinesis, puoi aggiungere record di dati al flusso e leggere i dati dal flusso. L'aggiunta di record di dati implica la chiamata all'[PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html#API_PutRecord_Examples)azione [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html#API_PutRecords_Examples)o in Kinesis. La prima operazione aggiunge più record, la seconda aggiunge un singolo record al flusso.
```
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"
}
```
oppure
```
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"
}
```
Qui `StreamName` identifica il flusso di destinazione per aggiungere record. `StreamName`, `Data`, e `PartitionKey` sono dati di input obbligatori. Nel nostro esempio useremo i valori predefiniti per tutti i dati di input facoltativi e non ne specificheremo in modo esplicito i valori nell'input per la richiesta del metodo.
Leggere i dati in Kinesis equivale a richiamare l'azione [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html#API_GetRecords_Examples):
```
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
}
```
Qui il flusso di origine da cui vogliamo ottenere record è specificato nel valore `ShardIterator` obbligatorio, come mostrato nell'operazione di Kinesis seguente per ottenere un'iterazione shard:
```
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"
}
```
Per le operazioni `GetRecords` e `PutRecords`, esponiamo rispettivamente i metodi `GET` e `PUT` in una risorsa `/records` che viene aggiunta a una risorsa flusso denominata (`/{stream-name}`). Analogamente, esponiamo l'operazione `PutRecord` come metodo `PUT` in una risorsa `/record`.
Poiché l'operazione `GetRecords` accetta come input un valore `ShardIterator`, ottenuto chiamando l'operazione helper `GetShardIterator`, esponiamo un metodo helper `GET` in una risorsa `ShardIterator` (`/sharditerator`).
**Per creare le risorse /record, /records e /sharditerator**
1. Scegli la risorsa **/\$1stream-name\$1**, quindi seleziona **Crea risorsa**.
1. Mantieni l'opzione **Risorsa proxy** disattivata.
1. Per **Percorso risorsa** seleziona `/{stream-name}`.
1. Per **Resource Name (Nome risorsa)** immetti **record**.
1. Mantieni **CORS (Cross Origin Resource Sharing)** disattivato.
1. Scegli **Crea risorsa**.
1. Ripeti le fasi precedenti per creare una risorsa **/records** e una risorsa **/sharditerator**. L'API finale sarà simile alla seguente:
![\[Creazione del metodo Records:GET|PUT|PUT|GET per l'API.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-kinesis-proxy-setup-streams-stream-record-method-new-console.png)
Le quattro procedure seguenti descrivono come configurare ognuno dei metodi, come mappare i dati dalle richieste dei metodi alle richieste di integrazione e come testare i metodi.
**Per configurare e testare il metodo `PUT /streams/{stream-name}/record` per richiamare `PutRecord` in Kinesis:**
1. Scegli la risorsa **/record**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **PUT**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **PutRecord**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi i seguenti **parametri delle intestazioni delle richieste URL**:
```
Content-Type: 'x-amz-json-1.1'
```
L'attività segue la stessa procedura usata per configurare la mappatura dei parametri di richiesta per il metodo `GET /streams`.
1. Aggiungi il modello di mappatura del corpo seguente per mappare i dati dalla richiesta del metodo `PUT /streams/{stream-name}/record` alla richiesta di integrazione corrispondente di `POST /?Action=PutRecord`:
```
{
"StreamName": "$input.params('stream-name')",
"Data": "$util.base64Encode($input.json('$.Data'))",
"PartitionKey": "$input.path('$.PartitionKey')"
}
```
Questo modello di mappatura presuppone che il payload della richiesta del metodo abbia il formato seguente:
```
{
"Data": "some data",
"PartitionKey": "some key"
}
```
Questi dati possono essere modellati tramite lo schema JSON seguente:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PutRecord proxy single-record payload",
"type": "object",
"properties": {
"Data": { "type": "string" },
"PartitionKey": { "type": "string" }
}
}
```
Puoi creare un modello per includere questo schema e usare il modello per semplificare la generazione del modello di mappatura. Tuttavia, puoi generare un modello di mappatura senza usare alcun modello.
1. Per testare il metodo `PUT /streams/{stream-name}/record`, imposta la variabile di percorso `stream-name` sul nome di un flusso esistente, fornisci un payload con il formato richiesto e quindi invia la richiesta del metodo. Il risultato con esito positivo è una risposta `200 OK `con un payload nel formato seguente:
```
{
"SequenceNumber": "49559409944537880850133345460169886593573102115167928386",
"ShardId": "shardId-000000000004"
}
```
**Per configurare e testare il metodo `PUT /streams/{stream-name}/records` per richiamare `PutRecords` in Kinesis**
1. Scegli la risorsa **/records**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **PUT**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **PutRecords**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi i seguenti **parametri delle intestazioni delle richieste URL**:
```
Content-Type: 'x-amz-json-1.1'
```
L'attività segue la stessa procedura usata per configurare la mappatura dei parametri di richiesta per il metodo `GET /streams`.
1. Aggiungi il modello di mappatura seguente per mappare i dati dalla richiesta del metodo `PUT /streams/{stream-name}/records` alla richiesta di integrazione corrispondente di `POST /?Action=PutRecords`:
```
{
"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
]
}
```
Questo modello di mappatura presuppone che il payload della richiesta del metodo possa essere modellato tramite lo schema JSON seguente:
```
{
"$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" }
}
}
}
}
}
```
Puoi creare un modello per includere questo schema e usare il modello per semplificare la generazione del modello di mappatura. Tuttavia, puoi generare un modello di mappatura senza usare alcun modello.
In questo tutorial abbiamo usato due formati di payload leggermente diversi per mostrare come uno sviluppatore di API possa scegliere di esporre il formato di dati di back-end al client o nasconderlo dal client. Un formato è per il metodo `PUT /streams/{stream-name}/records` (sopra). Un altro formato viene usato per il metodo `PUT /streams/{stream-name}/record` (nella procedura precedente). Nell'ambiente di produzione devi mantenere i due formati coerenti.
1.
Per testare il metodo `PUT /streams/{stream-name}/records`, imposta la variabile di percorso `stream-name` su un flusso esistente, fornisci il payload seguente e invia la richiesta del metodo.
```
{
"records": [
{
"data": "some data",
"partition-key": "some key"
},
{
"data": "some other data",
"partition-key": "some key"
}
]
}
```
Il risultato con esito positivo è una risposta 200 OK con un payload simile all'output seguente:
```
{
"FailedRecordCount": 0,
"Records": [
{
"SequenceNumber": "49559409944537880850133345460167468741933742152373764162",
"ShardId": "shardId-000000000004"
},
{
"SequenceNumber": "49559409944537880850133345460168677667753356781548470338",
"ShardId": "shardId-000000000004"
}
]
}
```
**Per configurare e testare il metodo `GET /streams/{stream-name}/sharditerator` per richiamare `GetShardIterator` in Kinesis**
Il metodo `GET /streams/{stream-name}/sharditerator` è un metodo helper per acquisire un'iterazione shard necessaria prima di chiamare il metodo `GET /streams/{stream-name}/records`.
1. Scegli la risorsa **/sharditerator**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **GetShardIterator**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Parametri della stringa di query URL**.
L'operazione `GetShardIterator` richiede l'immissione di un valore ShardId. Per passare un valore `ShardId` fornito dal client, aggiungiamo un parametro di query `shard-id` alla richiesta del metodo, come mostrato nella seguente fase.
1. Scegliere **Add query string (Aggiungi stringa di query)**.
1. In **Nome**, inserisci **shard-id**.
1. Mantieni **Obbligatorio** e **Caching** disattivati.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi il seguente modello di mappatura per generare l'input richiesto (`ShardId` e `StreamName`) per l'azione `GetShardIterator` dei parametri `shard-id` e `stream-name` della richiesta del metodo. Inoltre, il modello di mappatura imposta anche `ShardIteratorType` su `TRIM_HORIZON` come comportamento predefinito.
```
{
"ShardId": "$input.params('shard-id')",
"ShardIteratorType": "TRIM_HORIZON",
"StreamName": "$input.params('stream-name')"
}
```
1. Usando l'opzione **Test** nella console API Gateway, immetti il nome di un flusso esistente come valore della variabile `stream-name`**Path (Percorso)**, imposta `shard-id`**Query string (Stringa di query)** su un valore `ShardId` esistente, ad esempio `shard-000000000004`, e seleziona **Test**.
Il payload di risposta di esito positivo è simile all'output seguente:
```
{
"ShardIterator": "AAAAAAAAAAFYVN3VlFy..."
}
```
Annota il valore di `ShardIterator`. Ti servirà per ottenere record da un flusso.
**Per configurare e testare il metodo `GET /streams/{stream-name}/records` per richiamare l'operazione `GetRecords` in Kinesis**
1. Scegli la risorsa **/records**, quindi seleziona **Crea metodo**.
1. Per **Tipo di metodo** seleziona **GET**.
1. Per **Tipo di integrazione** seleziona **Servizio AWS **.
1. Per **Regione AWS**, seleziona il Regione AWS luogo in cui hai creato lo stream Kinesis.
1. Per **Servizio AWS** seleziona **Kinesis**.
1. Lascia vuoto **Sottodominio AWS **.
1. Per **HTTP method** (Metodo HTTP) scegli **POST**.
1. Per **Tipo di operazione** scegli **Usa nome operazione**.
1. Per **Nome azione** immetti **GetRecords**.
1. Per **Ruolo di esecuzione** immetti l'ARN del ruolo di esecuzione.
1. Lascia il valore predefinito **Transito** per **Gestione contenuti**.
1. Scegli **Intestazioni di richiesta HTTP**.
L'operazione `GetRecords` richiede l'immissione di un valore `ShardIterator`. Per passare un valore `ShardIterator` fornito dal client, si aggiunge un parametro di intestazione `Shard-Iterator` alla richiesta del metodo.
1. Seleziona **Add header (Aggiungi intestazione)**.
1. In **Nome**, inserisci **Shard-Iterator**.
1. Mantieni **Obbligatorio** e **Caching** disattivati.
1. Scegli **Crea metodo**.
1. Nella sezione **Richiesta di integrazione** aggiungi il seguente modello di mappatura del corpo per mappare il valore del parametro di intestazione `Shard-Iterator` al valore della proprietà `ShardIterator` del payload JSON per l'azione `GetRecords` in Kinesis.
```
{
"ShardIterator": "$input.params('Shard-Iterator')"
}
```
1. Usando l'opzione **Test** nella console Gateway API, immetti il nome di un flusso esistente come valore della variabile **Percorso** `stream-name`, imposta **Intestazione** `Shard-Iterator` sul valore `ShardIterator` ottenuto dall'esecuzione del test del metodo `GET /streams/{stream-name}/sharditerator` (precedente) e scegli **Test**.
Il payload di risposta di esito positivo è simile all'output seguente:
```
{
"MillisBehindLatest": 0,
"NextShardIterator": "AAAAAAAAAAF...",
"Records": [ ... ]
}
```