Vendi le API Gateway API tramite Marketplace AWS

Dopo aver creato, testato e implementato le tue API, puoi pacchettizzarle in un piano di utilizzo di API Gateway e vendere il piano come prodotto Software-as-a-Service (SaaS) tramite Marketplace AWS. Gli acquirenti dell'API che sottoscrivono la tua offerta di prodotto ricevono una fattura da Marketplace AWS in base al numero di richieste effettuate al piano di utilizzo.

Per vendere le tue API su Marketplace AWS, devi impostare il canale di vendita in modo che Marketplace AWS sia integrato in API Gateway. In linea generale, questo implica l'inserimento del tuo prodotto in Marketplace AWS, la configurazione di un ruolo IAM con le policy richieste per consentire ad API Gateway di inviare parametri di utilizzo a Marketplace AWS, l'associazione di un prodotto Marketplace AWS a un piano di utilizzo API Gateway e l'associazione di un acquirente Marketplace AWS a una chiave API Gateway. I dettagli vengono approfonditi nelle sezioni seguenti.

Per ulteriori informazioni sulla vendita delle tue API come prodotto SaaS su Marketplace AWS, consulta la Marketplace AWS Guida per l'utente.

Inizializzazione dell'integrazione di Marketplace AWS con API Gateway

Le seguenti attività sono finalizzate all'inizializzazione una-tantum dell'integrazione di Marketplace AWS con API Gateway, per consentirti di vendere le tue API come prodotto SaaS.

Inserimento di un prodotto su Marketplace AWS

Per inserire il tuo piano di utilizzo come prodotto SaaS, invia un modulo di caricamento prodotto tramite Marketplace AWS. Il prodotto deve contenere una dimensione denominata apigateway del tipo requests. La dimensione definisce il prezzo per richiesta e viene utilizzata da API Gateway per misurare le richieste effettuate alle tue API.

Creazione del ruolo di misurazione

Crea un ruolo IAM denominato ApiGatewayMarketplaceMeteringRole con le seguenti policy di esecuzione e policy di attendibilità. Questo ruolo consente ad API Gateway di inviare parametri di utilizzo a Marketplace AWS per tuo conto.

Policy di esecuzione del ruolo di misurazione

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "aws-marketplace:BatchMeterUsage",
        "aws-marketplace:ResolveCustomer"
      ],
      "Resource": "*",
      "Effect": "Allow"
    }
  ]
}

Policy di relazione di fiducia del ruolo di misurazione

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "apigateway.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Associazione del piano di utilizzo con il prodotto Marketplace AWS

Quando inserisci un prodotto su Marketplace AWS, ricevi un codice prodotto Marketplace AWS. Per integrare API Gateway e Marketplace AWS, associa il tuo piano di utilizzo al codice prodotto Marketplace AWS. È possibile abilitare l'associazione impostando il campo UsagePlan dello productCode di API Gateway al codice prodotto Marketplace AWS, utilizzando la console API Gateway, l'API REST di API Gateway, la AWS CLI per API Gateway o l'SDK AWS per API Gateway. Nell'esempio di codice seguente viene utilizzata l'API REST dell'API Gateway:

PATCH /usageplans/USAGE_PLAN_ID
Host: apigateway.region.amazonaws.com
Authorization: ...

{
    "patchOperations" : [{
        "path" : "/productCode",
        "value" : "MARKETPLACE_PRODUCT_CODE",
        "op" : "replace"
    }]
}

Gestione della sottoscrizione del cliente ai piani di utilizzo

Le seguenti attività sono gestite dall'applicazione del portale sviluppatore.

Quando un cliente sottoscrive il tuo prodotto tramite Marketplace AWS, Marketplace AWS inoltra una richiesta POST all'URL di sottoscrizione SaaS che hai registrato quando hai inserito il tuo prodotto su Marketplace AWS. La richiesta POST presenta un parametro x-amzn-marketplace-token contenente le informazioni sull'acquirente. Segui le istruzioni riportate in Onboarding dei clienti SaaS per gestire questo reindirizzamento nell'applicazione del portale per gli sviluppatori.

Nel rispondere a una richiesta di sottoscrizione di un cliente, Marketplace AWS invia una notifica subscribe-success a un argomento Amazon SNS che puoi sottoscrivere (Consulta Onboarding dei clienti SaaS). Per accettare la richiesta di sottoscrizione del cliente, devi gestire la notifica subscribe-success creando o recuperando una chiave API Gateway per il cliente, associando il Marketplace AWS fornito da customerId del cliente alle chiavi API, quindi aggiungendo la chiave API al tuo piano di utilizzo.

Quando la richiesta di sottoscrizione del cliente è completa, l'applicazione del portale per gli sviluppatori deve mostrare al cliente la chiave API associata e informarlo che la chiave API deve essere inclusa nell'intestazione x-api-key quando si effettuano le richieste alle API.

Quando un cliente annulla una sottoscrizione a un piano di utilizzo, Marketplace AWS invia una notifica unsubscribe-success all'argomento SNS. Per portare a termine il processo di cancellazione di un cliente, devi gestire la notifica unsubscribe-success eliminando le chiavi API del cliente dal piano di utilizzo.

Per autorizzare un cliente ad accedere a un piano di utilizzo

Per autorizzare un cliente ad accedere al tuo piano di utilizzo, usa l'API di API Gateway per recuperare o creare una chiave API per il cliente e aggiungerla al piano di utilizzo.

Il seguente esempio mostra come chiamare l'API REST API Gateway per creare una nuova chiave API con un valore Marketplace AWS customerId specifico (MARKETPLACE_CUSTOMER_ID).

POST apikeys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

{
  "name" : "my_api_key",
  "description" : "My API key",
  "enabled" : "false",
  "stageKeys" : [ {
    "restApiId" : "uycll6xg9a",
    "stageName" : "prod"
  } ],
  "customerId" : "MARKETPLACE_CUSTOMER_ID"
}

Il seguente esempio mostra come ottenere una chiave API con un valore Marketplace AWS specifico customerId (MARKETPLACE_CUSTOMER_ID).

GET apikeys?customerId=MARKETPLACE_CUSTOMER_ID HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

Per aggiungere una chiave API a un piano di utilizzo, crea un UsagePlanKey con la chiave API per il relativo piano di utilizzo. Il seguente esempio mostra come ottenere tale risultato utilizzando l'API REST di API Gateway, dove n371pt è l'ID del piano di utilizzo e q5ugs7qjjh è un esempio di keyId API restituito dagli esempi precedenti.

POST /usageplans/n371pt/keys HTTP/1.1
Host: apigateway.region.amazonaws.com
Authorization: ...

{
    "keyId": "q5ugs7qjjh",
    "keyType": "API_KEY"
}

Per associare un cliente a una chiave API

Devi aggiornare il campo di ApiKey customerId con l'ID cliente Marketplace AWS del cliente. In questo modo, la chiave API viene associata al cliente Marketplace AWS, attivando così misurazione e fatturazione per l'acquirente. Il seguente esempio di codice invoca l'API REST API Gateway per ottenere tale risultato.

PATCH /apikeys/q5ugs7qjjh
Host: apigateway.region.amazonaws.com
Authorization: ...
        
{
    "patchOperations" : [{
        "path" : "/customerId",
        "value" : "MARKETPLACE_CUSTOMER_ID",
        "op" : "replace"
    }]
}