Come posso usare il Gateway API come proxy per un altro servizio AWS?

12 minuti di lettura

Voglio utilizzare il Gateway Amazon API come proxy per un altro servizio AWS e integrare altri servizi con il Gateway API.

Breve descrizione

Le API dei servizi AWS sono essenzialmente REST API a cui puoi inviare una richiesta HTTPS. Puoi integrare molti servizi AWS con il Gateway API, ma la configurazione e la mappatura variano in base alla particolare API del servizio.

Per integrare un altro servizio con il Gateway API, crea una richiesta HTTPS dal Gateway API all'API del servizio. In questo modo, tutti i parametri della richiesta vengono mappati correttamente.

Questo articolo descrive un esempio di configurazione per l'integrazione dell'API Publish (Pubblicazione) di Amazon Simple Notification Service (Amazon SNS) con API Gateway. Usa questo esempio come schema per l'integrazione di altri servizi.

Soluzione

Nota: In caso di errori durante l'esecuzione dei comandi dell'interfaccia della linea di comando AWS (AWS CLI), assicurati di utilizzare la versione più recente di AWS CLI.

Configura gli strumenti e le risorse necessari

Configura il tuo ambiente e crea tutte le risorse AWS necessarie per il tuo caso d'uso. Per la configurazione di esempio di Amazon SNS, procedi come segue:

Installa l'interfaccia della linea di comando AWS.
Crea un argomento Amazon SNS. Annota il nome della risorsa Amazon (ARN) dell'argomento. Usa questa informazione nel passaggio seguente e successivamente in questa configurazione.
Crea una sottoscrizione all'argomento.
Apri la console AWS Identity and Access Management (IAM) e crea un ruolo di esecuzione del proxy del servizio AWS. Annota l'ARN del ruolo per una fase successiva della configurazione. Questo ruolo IAM fornisce al Gateway API le autorizzazioni come entità affidabile per assumere il servizio ed eseguire l'azione API che stai integrando. Per la configurazione di esempio di Amazon SNS, autorizza l'azione sns:Publish. Per ulteriori informazioni, consulta il modello di autorizzazioni Gateway API per richiamare un'API.
Crea una REST API del Gateway API con una risorsa di test. Per ulteriori informazioni ed esempi, consulta i tutorial e i workshop del Gateway Amazon API.
Nota: Facoltativamente, importa la REST API utilizzando la seguente definizione OpenAPI 2.0 (Swagger) di esempio. Questa opzione preconfigura le impostazioni per la configurazione di esempio di Amazon SNS. Assicurati di sostituire arn:aws:iam::account-id:role/apigateway-sns-role con l'ARN del tuo ruolo IAM. Sostituisci region (regione) con la regione AWS in cui vuoi creare la tua REST API.

{
  "swagger": "2.0",
  "info": {
    "version": "2019-10-09T14:10:24Z",
    "title": "aws-service-integration"
  },
  "basePath": "/dev",
  "schemes": [
    "https"
  ],
  "paths": {
    "/test": {
      "post": {
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "Message",
            "in": "query",
            "required": true,
            "type": "string"
          },
          {
            "name": "TopicArn",
            "in": "query",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "schema": {
              "$ref": "#/definitions/Empty"
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "credentials": "arn:aws:iam::account-id:role/apigateway-sns-role",
          "uri": "arn:aws:apigateway:region:sns:action/Publish",
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "requestParameters": {
            "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
            "integration.request.querystring.Message": "method.request.querystring.Message"
          },
          "passthroughBehavior": "when_no_match",
          "httpMethod": "POST",
          "type": "aws"
        }
      }
    }
  },
  "definitions": {
    "Empty": {
      "type": "object",
      "title": "Empty Schema"
    }
  }
}

Ottieni un esempio di richiesta HTTPS

Un esempio di richiesta HTTPS dall'API del servizio che stai integrando può aiutarti a mappare correttamente i parametri della richiesta nel Gateway API. Per ottenere un esempio di richiesta HTTPS, esegui una delle seguenti operazioni:

Controlla gli esempi nella documentazione dell'API. Per l'API Publish di Amazon SNS, puoi fare riferimento all'API Reference del servizio per una richiesta di esempio:

https://sns.us-west-2.amazonaws.com/?Action=Publish
&TargetArn=arn%3Aaws%3Asns%3Aus-west-2%3A803981987763%3Aendpoint%2FAPNS_SANDBOX%2Fpushapp%2F98e9ced9-f136-3893-9d60-776547eafebb
&Message=%7B%22default%22%3A%22This+is+the+default+Message%22%2C%22APNS_SANDBOX%22%3A%22%7B+%5C%22aps%5C%22+%3A+%7B+%5C%22alert%5C%22+%3A+%5C%22You+have+got+email.%5C%22%2C+%5C%22badge%5C%22+%3A+9%2C%5C%22sound%5C%22+%3A%5C%22default%5C%22%7D%7D%22%7D
&Version=2010-03-31
&AUTHPARAMS

- oppure -

Generalo da una chiamata API. Usa l'interfaccia della linea di comando AWS per richiamare l'API del servizio e quindi analizzare l'output. Determina il comando AWS CLI corrispondente per l'API del servizio che stai integrando, quindi esegui una richiesta di test con l'opzione**--debug**.

Suggerimento: Controlla il riferimento ai comandi dell’interfaccia della linea di comando AWS per trovare il comando AWS CLI corrispondente.

Per la configurazione di esempio di Amazon SNS, esegui questo comando:

Nota: Sostituisci arn:aws:sns:us-east-1:123456789012:test con l'ARN del tuo argomento Amazon SNS.

$ aws sns publish --topic-arn arn:aws:sns:us-east-1:123456789012:test --message "hi" --debug

L'output del comando contiene la richiesta HTTPS e le intestazioni passate. Ecco un esempio di cosa cercare:

2018-11-22 11:56:39,647 - MainThread - botocore.client - DEBUG - Registering retry handlers for service: sns
2018-11-22 11:56:39,648 - MainThread - botocore.hooks - DEBUG - Event before-parameter-build.sns.Publish: calling handler <function generate_idempotent_uuid at 0x11093d320>
2018-11-22 11:56:39,649 - MainThread - botocore.endpoint - DEBUG - Making request for OperationModel(name=Publish) (verify_ssl=True) with params: {'body': {'Action': u'Publish', u'Message': u'hello', 'Version': u'2010-03-31', u'TopicArn': u'arn:aws:sns:us-east-1:123456789012:test'}, 'url': u'https://sns.us-east-1.amazonaws.com/', 'headers': {'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8', 'User-Agent': 'aws-cli/1.15.74 Python/2.7.14 Darwin/16.7.0 botocore/1.9.23'}, 'context': {'auth_type': None, 'client_region': 'us-east-1', 'has_streaming_input': False, 'client_config': <botocore.config.Config object at 0x1118437d0>}, 'query_string': '', 'url_path': '/', 'method': u'POST'}
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event request-created.sns.Publish: calling handler <bound method RequestSigner.handler of <botocore.signers.RequestSigner object at 0x111843750>>
2018-11-22 11:56:39,650 - MainThread - botocore.hooks - DEBUG - Event choose-signer.sns.Publish: calling handler <function set_operation_specific_signer at 0x11093d230>
2018-11-22 11:56:39,650 - MainThread - botocore.auth - DEBUG - Calculating signature using v4 auth.
2018-11-22 11:56:39,651 - MainThread - botocore.auth - DEBUG - CanonicalRequest:
POST
/

content-type:application/x-www-form-urlencoded; charset=utf-8
host:sns.us-east-1.amazonaws.com
x-amz-date:20181122T062639Z

content-type;host;x-amz-date

In questo esempio, la richiesta viene inviata come metodo HTTP POST.

Crea un metodo per la tua API del Gateway API

Nella console Gateway API, nel riquadro APIs, scegli il nome della tua API.
Nel riquadro Resources (Risorse), scegli una risorsa. Per la configurazione di esempio di Amazon SNS, scegli la risorsa di test che hai creato.
Scegli Actions (Azioni), quindi scegli Create Method (Crea metodo).
Nell'elenco a discesa, scegli il metodo utilizzato dall'API del servizio nella richiesta HTTPS di esempio. (Per la configurazione di esempio di Amazon SNS, scegli POST.) Quindi, seleziona l'icona del segno di spunta.
Nel riquadro Setup (Configurazione), effettua le seguenti operazioni:
Per Integration type (Tipo di integrazione), scegli ** AWS Service** (Servizio AWS).
Per AWS Region (Regione AWS), scegli la regione AWS della risorsa associata all'API del servizio che stai integrando. Per la configurazione di esempio di Amazon SNS, scegli la regione del tuo argomento SNS.
Per AWS Service (Servizio AWS), scegli il servizio che stai integrando con Gateway API. Ad esempio, Simple Notification Service (SNS).
(Facoltativo) Per AWS Subdomain (Sottodominio AWS), inserisci il sottodominio utilizzato dal servizio AWS. Consulta la documentazione del servizio per confermare la disponibilità di un sottodominio. Lascia vuoto il campo relativo alla configurazione di esempio di Amazon SNS.
In HTTP method (Metodo HTTP), scegli il metodo che corrisponde all'API del servizio AWS che stai integrando. Come configurazione di esempio di Amazon SNS, scegli POST.
Per Action Type (Tipo di azione), se l'API del servizio che stai integrando è un'azione supportata, scegli Use action name (Usa il nome dell'azione). Controlla il riferimento API del servizio per avere l'elenco delle azioni supportate. Per Amazon SNS, consulta Actions (Azioni).
Per Action (Azione), inserisci il nome dell'API del servizio. Per la configurazione di esempio di Amazon SNS, inserisci Publish.
-oppure-
Per Action Type (Tipo di azione), se l'API del servizio AWS prevede un percorso di risorse nella tua richiesta, scegli Use path override (Usa la sovrascrittura del percorso). Ad esempio, per l'API ListLexicons di Amazon Polly, inserisci /v1/lexicons come Path override (optional) (Sovrascrittura del percorso (facoltativo)).
Per Execution role (Ruolo di esecuzione), inserisci l'ARN del ruolo IAM che hai creato.
(Facoltativo) Per Content Handling (Gestione dei contenuti) e Use Default Timeout (Usa il timeout predefinito), apporta le modifiche necessarie per il tuo caso d'uso. Per la configurazione di esempio di Amazon SNS, non modificare queste impostazioni.
Scegli Save (Salva).

Crea parametri per la richiesta del metodo

Determina i parametri di richiesta obbligatori e facoltativi per l'API del servizio che stai integrando. Per identificare questi parametri, fai riferimento alla richiesta HTTPS di esempio che hai ricevuto in precedenza o fai riferimento al riferimento API per l'API del servizio. Ad esempio, vedi Pubblica.

Nella console Gateway API, nel riquadro Method Execution (Esecuzione metodo) per il metodo dell'API del Gateway API, scegli Method Request (Richiesta del metodo).
(Facoltativo) Nel riquadro Method Request (Richiesta del metodo), per Request Validator (Validatore della richiesta), scegli un validatore della richiesta, un corpo e un'intestazione se desideri convalidare i parametri della stringa di query.
Espandi URL Query String Parameters (Parametri della stringa di query URL).
Scegli Add query string (Aggiungi stringa di query).
In Name (Nome), inserisci il nome di un parametro di richiesta per l'API del servizio che stai integrando.
Scegli l'icona del segno di spunta (Create a new query string (Crea una nuova stringa di query)).
Se il parametro è obbligatorio, seleziona la casella di controllo in Required (Obbligatorio).
Ripeti i passaggi da 4 a 7 per tutti i parametri della richiesta che desideri includere. Per la configurazione di esempio di Amazon SNS, crea un parametro chiamato T****opicArn e un altro denominato Message.

Per ulteriori informazioni, consulta Configura un metodo utilizzando la console Gateway API.

Nota: Per alcune API di servizio, devi inviare le intestazioni e il corpo richiesti nella richiesta di integrazione oltre ai parametri richiesti. Puoi creare le intestazioni e il corpo nel riquadro Integration Request (Richiesta di integrazione) in HTTP Request Headers (Intestazioni della richiesta HTTP) e Request Body (Corpo della richiesta).

Ad esempio, se stai integrando l'API Amazon Rekognition ListCollections, crea l'intestazione X-Amz-Target: RekognitionService.ListCollections. La richiesta è simile alla seguente:

POST https://rekognition.us-west-2.amazonaws.com/ HTTP/1.1
    Host: rekognition.us-west-2.amazonaws.com
    Accept-Encoding: identity
    Content-Length: 2
    X-Amz-Target: RekognitionService.ListCollections
    X-Amz-Date: 20170105T155800Z
    User-Agent: aws-cli/1.11.25 Python/2.7.9 Windows/8 botocore/1.4.82
    Content-Type: application/x-amz-json-1.1
    Authorization: AWS4-HMAC-SHA256 Credential=XXXXXXXX/20170105/us-west-2/rekognition/aws4_request,
      SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=XXXXXXXX

    {}

Se stai integrando l'API SendMessage di Amazon Simple Queue Service (Amazon SQS), mappa il corpo della richiesta utilizzando l'espressione di mappatura method.request.body.JSONPath_EXPRESSION. (Sostituisci JSONPath_EXPRESSION con un'espressione JSONPath per un campo JSON del corpo della richiesta). In questo esempio, una richiesta è simile alla seguente:

{'url_path': '/', 'query_string': '', 'method': 'POST',
'headers': {'Content-Type': 'application/x-www-form-urlencoded;
charset=utf-8', 'User-Agent': 'aws-cli/1.16.81 Python/3.6.5 Darwin/18.7.0 botocore/1.12.183'},
'body': {'Action': 'SendMessage', 'Version': '2012-11-05', 'QueueUrl': 'https://sqs.ap-southeast-2.amazonaws.com/123456789012/test01', 'MessageBody': 'Hello'},
'url': 'https://ap-southeast-2.queue.amazonaws.com/', 'context': {'client_region': 'ap-southeast-2', 'client_config': <botocore.config.Config object at 0x106862da0>, 'has_streaming_input': False, 'auth_type': None}}

Crea parametri per la richiesta di integrazione

Mappa i parametri che hai creato per la richiesta del metodo ai parametri per la richiesta di integrazione.

Nella console Gateway API, torna al riquadro Method Execution (Esecuzione metodo) per il metodo dell'API del Gateway API, quindi scegli Integration Request (Richiesta di integrazione).
Nel riquadro Integration Request (Richiesta di integrazione), espandi URL Query String Parameters (Parametri della stringa di query URL).
Scegli Add query string (Aggiungi stringa di query).
In Name (Nome), inserisci il nome di un parametro di richiesta per l'API del servizio che stai integrando.
Nota: Il nome fa distinzione tra maiuscole e minuscole e deve apparire esattamente come previsto dall'API del servizio.
In Mapped from (Mappato da), inserisci method.request.querystring.param_name. Sostituisci param_name con il nome del parametro corrispondente che hai creato per la richiesta del metodo. Ad esempio, method.request.querystring.TopicArn.
Scegli l'icona del segno di spunta (Create (Crea)).
Ripeti i passaggi 3-6 e crea parametri per la richiesta di integrazione che corrispondono a ciascuno dei parametri che hai creato per la richiesta del metodo.

Nota: Se hai creato le intestazioni e il corpo necessari per la richiesta del metodo, mappali anche alla richiesta di integrazione. Creali nel riquadro Integration Request (Richiesta di integrazione) sotto HTTP Headers (Intestazioni HTTP) e Mapping Templates (Modelli di mappatura).

Per ulteriori informazioni, consulta Configura una richiesta di integrazione API utilizzando la console Gateway API.

(Facoltativo) Controlla la tua configurazione di integrazione

Per confermare che la configurazione dell'integrazione sia quella prevista, puoi eseguire il comando AWS CLI get-integration per verificare una configurazione simile alla seguente:

$ aws apigateway get-integration --rest-api-id 1234123412 --resource-id y9h6rt --http-method POST

Per la configurazione di esempio di Amazon SNS, l'output è simile al seguente:

{
    "integrationResponses": {
        "200": {
            "responseTemplates": {
                "application/json": null
            },
            "statusCode": "200"
        }
    },
    "passthroughBehavior": "WHEN_NO_MATCH",
    "timeoutInMillis": 29000,
    "uri": "arn:aws:apigateway:us-east-2:sns:action/Publish",
    "httpMethod": "POST",
    "cacheNamespace": "y9h6rt",
    "credentials": "arn:aws:iam::1234567890:role/apigateway-sns-role",
    "type": "AWS",
    "requestParameters": {
        "integration.request.querystring.TopicArn": "method.request.querystring.TopicArn",
        "integration.request.querystring.Message": "method.request.querystring.Message"
    },
    "cacheKeyParameters": []
}

Nella console Gateway API, torna al riquadro Method Execution (Esecuzione metodo) per il metodo dell'API del Gateway API, quindi scegli TEST.

Nel riquadro Method Test (Test metodo), effettua le seguenti operazioni:
In Query Strings (Stringhe di query), inserisci una stringa di query che includa i parametri e i valori della richiesta. Per la configurazione di esempio di Amazon SNS, inserisci TopicArn= arn:aws:sns:us-east-1:123456789012:test&Message="Hello". Sostituisci arn:aws:sns:us-east-1:123456789012:test con l'ARN del tuo argomento Amazon SNS.
Per Headers (Intestazioni) e Request Body (Corpo richiesta), se li hai creati per la tua configurazione, inserisci i nomi delle intestazioni e il JSON del corpo della richiesta.
Scegli Test. Nel riquadro Method Test (Test metodo) viene visualizzata una risposta. Se la risposta ha esito positivo, viene visualizzato Status: 200. Per la configurazione di esempio di Amazon SNS, una risposta corretta include un MessageId nel corpo della risposta.
Per ulteriori informazioni, consulta Utilizza la console Gateway API per testare un metodo REST API.
Implementa la tua REST API.
Testa la tua API utilizzando tutti gli strumenti che preferisci.