Salta ai contenuti
@aws/nx-plugin
Blog

Smithy TypeScript API

Smithy è un linguaggio di definizione di interfacce indipendente dal protocollo per la creazione di API in modo model-driven.

Il generatore Smithy TypeScript API crea una nuova API utilizzando Smithy per la definizione del servizio e il Smithy TypeScript Server SDK per l’implementazione. Il generatore fornisce infrastruttura come codice CDK o Terraform per distribuire il servizio su AWS Lambda, esposto tramite un’API REST di AWS API Gateway. Fornisce sviluppo API type-safe con generazione automatica del codice dai modelli Smithy. L’handler generato utilizza AWS Lambda Powertools for TypeScript per l’osservabilità, inclusi logging, tracing AWS X-Ray e CloudWatch Metrics

Utilizzo

Sezione intitolata “Utilizzo”

Generare una Smithy TypeScript API

Sezione intitolata “Generare una Smithy TypeScript API”

Puoi generare una nuova Smithy TypeScript API in due modi:

Esegui questo generatore@aws/nx-plugin:ts#api

pnpm nx g @aws/nx-plugin:ts#api
Componi il tuo comando10

Obbligatorio

framework = smithy

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

Opzioni

Sezione intitolata “Opzioni”
Opzioni del generatore10 opzioni
nameObbligatoriostring

Il nome dell'API (obbligatorio). Utilizzato per generare i nomi delle classi e i percorsi dei file.

frameworkenumPredefinito: trpc

Il framework API da utilizzare.

trpcsmithy
integrationPatternenumPredefinito: isolated

Come vengono generate le integrazioni API Gateway per l'API. Scegli tra isolated (predefinito) e shared.

isolatedshared
authenumPredefinito: iam

Il metodo utilizzato per autenticare con la tua API. Scegli tra iam (predefinito), cognito o custom.

iamcognitocustom
directorystringPredefinito: packages

La directory in cui memorizzare l'applicazione.

iacenumPredefinito: inherit

Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

inheritcdkterraform
infraenumPredefinito: rest-lambda

Il tipo di infrastruttura da utilizzare per distribuire questa API.

rest-lambdanone
namespacestringframework = smithy

Il namespace per l'API Smithy (applicabile solo per il framework smithy). Il valore predefinito è lo scope del monorepo

subDirectorystring

La sottodirectory in cui viene posizionato il progetto. Per impostazione predefinita corrisponde al nome del progetto.

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Sezione intitolata “Output del Generatore”

Il generatore crea due progetti correlati nella directory <directory>/<api-name>:

  • Directorymodel/ Progetto del modello Smithy
    • project.json Configurazione del progetto e target di build
    • smithy-build.json Configurazione di build Smithy
    • ssdk.rolldown.config.mjs Raggruppa il TypeScript Server SDK generato
    • Directorysrc/
      • main.smithy Definizione principale del servizio
      • Directoryoperations/
        • echo.smithy Definizione di operazione di esempio
  • Directorybackend/ Implementazione backend TypeScript
    • package.json Manifest del progetto che definisce il nome del pacchetto e le dipendenze
    • project.json Configurazione del progetto e target di build
    • rolldown.config.ts Configurazione del bundle
    • tsconfig.json Configurazione TypeScript
    • tsconfig.lib.json Configurazione TypeScript per i sorgenti della libreria
    • tsconfig.spec.json Configurazione TypeScript per i test
    • vitest.config.mts Configurazione Vitest
    • Directorysrc/
      • index.ts Punto di ingresso del pacchetto
      • handler.ts Handler AWS Lambda
      • local-server.ts Server di sviluppo locale
      • service.ts Implementazione del servizio
      • context.ts Definizione del contesto del servizio
      • Directoryoperations/
        • echo.ts Implementazione di operazione di esempio
      • Directorygenerated/ SDK TypeScript generato (creato durante la build)
        • …

Infrastruttura

Sezione intitolata “Infrastruttura”

Poiché questo generatore crea infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

Il progetto comune di infrastruttura come codice è strutturato come segue:

  • Directorypackages/common/constructs
    • Directorysrc
      • Directoryapp/ Costrutti per l’infrastruttura specifica di un progetto/generatore
        • Directoryapis/
          • <project-name>.ts Costrutto CDK per distribuire la tua API
      • Directorycore/ Costrutti generici riutilizzati dai costrutti in app
        • Directoryapi/
          • rest-api.ts Costrutto CDK per distribuire un’API REST
          • utils.ts Utilità per i costrutti API
      • index.ts Punto di ingresso che esporta i costrutti da app
    • project.json Target di build e configurazione del progetto

Architettura

Sezione intitolata “Architettura”

L’API Smithy distribuita ha la seguente architettura, con un Web ACL AWS WAFv2 davanti allo stage API Gateway:

Loading the diagram…

Implementare la tua Smithy API

Sezione intitolata “Implementare la tua Smithy API”

Definire Operazioni in Smithy

Sezione intitolata “Definire Operazioni in Smithy”

Le operazioni sono definite in file Smithy all’interno del progetto del modello. La definizione principale del servizio è in main.smithy:

$version: "2.0"


namespace your.namespace


use aws.protocols#restJson1
use smithy.framework#ValidationException


@title("YourService")
@restJson1
service YourService {
    version: "1.0.0"
    operations: [
        Echo,
        // Add your operations here
    ]
    errors: [
        ValidationException
    ]
}

Le singole operazioni sono definite in file separati nella directory operations/:

$version: "2.0"


namespace your.namespace


@http(method: "POST", uri: "/echo")
operation Echo {
    input: EchoInput
    output: EchoOutput
}


structure EchoInput {
    @required
    message: String


    foo: Integer
    bar: String
}


structure EchoOutput {
    @required
    message: String
}

Aggiungere una Libreria di Shape

Sezione intitolata “Aggiungere una Libreria di Shape”

Se hai diverse API Smithy che condividono gli stessi tipi di dati, puoi definire quei tipi una volta in una libreria di shape piuttosto che duplicarli in ogni modello. Una libreria di shape è un progetto Smithy senza servizio — solo shape riutilizzabili — su cui qualsiasi numero di progetti Smithy può dipendere.

Generane una con il generatore smithy#project:

Esegui questo generatore@aws/nx-plugin:smithy#project

pnpm nx g @aws/nx-plugin:smithy#project
Componi il tuo comando7

Obbligatorio

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

Il modello della tua API può quindi fare riferimento alle sue shape con use:

$version: "2.0"


namespace com.example.api


use com.example.shared#Customer


structure GetCustomerOutput {
    @required
    customer: Customer
}

Consulta la guida al progetto Smithy per come creare una libreria di shape e collegarla come dipendenza del modello della tua API.

Implementare Operazioni in TypeScript

Sezione intitolata “Implementare Operazioni in TypeScript”

Le implementazioni delle operazioni si trovano nella directory src/operations/ del progetto backend. Ogni operazione è implementata utilizzando i tipi generati dal TypeScript Server SDK (generato al momento della build dal tuo modello Smithy).

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';


export const Echo: EchoOperation<ServiceContext> = async (input) => {
  // Your business logic here
  return {
    message: `Echo: ${input.message}` // type-safe based on your Smithy model
  };
};

Le operazioni devono essere registrate nella definizione del servizio in src/service.ts:

import { ServiceContext } from './context.js';
import { YourServiceService } from './generated/ssdk/index.js';
import { Echo } from './operations/echo.js';
// Import other operations here


// Register operations to the service here
export const Service: YourServiceService<ServiceContext> = {
  Echo,
  // Add other operations here
};

Contesto del Servizio

Sezione intitolata “Contesto del Servizio”

Puoi definire un contesto condiviso per le tue operazioni in context.ts:

export interface ServiceContext {
  // Powertools tracer, logger and metrics are provided by default
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  // Add shared dependencies, database connections, etc.
  dbClient: any;
  userIdentity: string;
}

Questo contesto viene passato a tutte le implementazioni delle operazioni e può essere utilizzato per condividere risorse come connessioni al database, configurazione o utilità di logging.

Osservabilità con AWS Lambda Powertools

Sezione intitolata “Osservabilità con AWS Lambda Powertools”

Logging

Sezione intitolata “Logging”

Il generatore configura il logging strutturato utilizzando AWS Lambda Powertools con iniezione automatica del contesto tramite middleware Middy.

handler.ts
export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Puoi fare riferimento al logger dalle implementazioni delle tue operazioni tramite il contesto:

operations/echo.ts
import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';


export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  ctx.logger.info('Your log message');
  // ...
};

Tracing

Sezione intitolata “Tracing”

Il tracing AWS X-Ray è configurato automaticamente tramite il middleware captureLambdaHandler.

handler.ts
export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Puoi aggiungere subsegment personalizzati alle tue tracce nelle tue operazioni:

operations/echo.ts
import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';


export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  // Creates a new subsegment
  const subsegment = ctx.tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Your logic here
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

Metriche

Sezione intitolata “Metriche”

Le metriche CloudWatch vengono raccolte automaticamente per ogni richiesta tramite il middleware logMetrics.

handler.ts
export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
  .use(captureLambdaHandler(tracer))
  .use(injectLambdaContext(logger))
  .use(logMetrics(metrics))
  .handler(lambdaHandler);

Puoi aggiungere metriche personalizzate nelle tue operazioni:

operations/echo.ts
import { MetricUnit } from '@aws-lambda-powertools/metrics';
import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';


export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  ctx.metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
  // ...
};

Gestione degli Errori

Sezione intitolata “Gestione degli Errori”

Smithy fornisce gestione degli errori integrata. Puoi definire errori personalizzati nel tuo modello Smithy:

@error("client")
@httpError(400)
structure InvalidRequestError {
    @required
    message: String
}

E registrarli alla tua operazione/servizio:

operation MyOperation {
  ...
  errors: [InvalidRequestError]
}

Quindi lanciarli nella tua implementazione TypeScript:

import { InvalidRequestError } from '../generated/ssdk/index.js';


export const MyOperation: MyOperationHandler<ServiceContext> = async (input) => {
  if (!input.requiredField) {
    throw new InvalidRequestError({
      message: "Required field is missing"
    });
  }


  return { /* success response */ };
};

Accedere all’Utente Chiamante

Sezione intitolata “Accedere all’Utente Chiamante”

Quando la tua API è protetta da autenticazione, le tue operazioni spesso devono sapere chi sta chiamando. L’approccio consigliato è risolvere l’identità del chiamante una volta nell’handler e passarla attraverso il contesto del servizio per il consumo da parte di operazioni specifiche.

Modelleremo il caso non autorizzato come un errore Smithy in modo che si serializzi in una risposta 403 appropriata. Aggiungilo al tuo modello, ad esempio in model/src/operations/errors.smithy, e fai riferimento ad esso su qualsiasi operazione che richiede l’identità:

$version: "2.0"


namespace your.namespace


/// Thrown when the calling user cannot be determined
@error("client")
@httpError(403)
structure UnauthorizedError {
    @required
    message: String
}

Prima, esponi l’identità risolta sul contesto del servizio in src/context.ts. La forniamo come funzione in modo che l’UnauthorizedError venga lanciato dall’interno di un’operazione (dove il Server SDK lo serializza in un 403), piuttosto che dall’handler:

import { Logger } from '@aws-lambda-powertools/logger';
import { Metrics } from '@aws-lambda-powertools/metrics';
import { Tracer } from '@aws-lambda-powertools/tracer';


export interface Identity {
  sub: string;
  username: string;
}


/**
 * Context provided to all operations.
 */
export interface ServiceContext {
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  getIdentity: () => Promise<Identity>;
}

Successivamente, scrivi il resolver in src/identity.ts. Lancia UnauthorizedError quando il chiamante non può essere determinato. L’implementazione dipende dal tuo metodo auth selezionato:

auth = iam

Per l’autenticazione IAM, cerchiamo il chiamante in Cognito utilizzando il sub estratto dall’evento API Gateway. La ricerca utilizza il client Cognito Identity Provider, che non è una dipendenza di un backend Smithy generato, quindi installalo prima nel progetto backend:

Terminal window
pnpm add @aws-sdk/client-cognito-identity-provider@3.1126.0 --filter my-api
import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
import type { APIGatewayProxyEvent } from 'aws-lambda';
import { Identity } from './context.js';
import { UnauthorizedError } from './generated/ssdk/index.js';


const cognito = new CognitoIdentityProvider();


export const getIdentity = async (
  event: APIGatewayProxyEvent,
): Promise<Identity> => {
  const cognitoAuthenticationProvider =
    event.requestContext?.identity?.cognitoAuthenticationProvider;


  let sub: string | undefined = undefined;
  if (cognitoAuthenticationProvider) {
    const providerParts = cognitoAuthenticationProvider.split(':');
    sub = providerParts[providerParts.length - 1];
  }


  if (!sub) {
    throw new UnauthorizedError({
      message: 'Unable to determine calling user',
    });
  }


  const { Users } = await cognito.listUsers({
    // Assumes user pool id is configured in lambda environment
    UserPoolId: process.env.USER_POOL_ID!,
    Limit: 1,
    Filter: `sub="${sub}"`,
  });


  if (!Users || Users.length !== 1) {
    throw new UnauthorizedError({
      message: `No user found with subjectId ${sub}`,
    });
  }


  return { sub, username: Users[0].Username! };
};
auth = cognito

Con auth: 'cognito', l’authorizer Cognito User Pools di API Gateway verifica il JWT che il chiamante fornisce nell’header Authorization e posiziona i claim verificati sull’evento in event.requestContext.authorizer.claims:

import type { APIGatewayProxyEvent } from 'aws-lambda';
import { Identity } from './context.js';
import { UnauthorizedError } from './generated/ssdk/index.js';


export const getIdentity = async (
  event: APIGatewayProxyEvent,
): Promise<Identity> => {
  const claims = event.requestContext?.authorizer?.claims as
    | Record<string, string>
    | undefined;


  const sub = claims?.sub;
  const username = claims?.username;


  if (!sub || !username) {
    throw new UnauthorizedError({
      message: 'Unable to determine calling user',
    });
  }


  return { sub, username };
};

Quindi collega il resolver al contesto in src/handler.ts:

import { Service } from './service.js';
import { getIdentity } from './identity.js';
// ...
const httpResponse = await serviceHandler.handle(httpRequest, {
  tracer,
  logger,
  metrics,
  getIdentity: () => getIdentity(event),
});

getIdentity è un campo obbligatorio su ServiceContext, e come nota la cautela sopra il contesto è costruito in entrambi i punti di ingresso — quindi anche src/local-server.ts ne ha bisogno. Non c’è alcun authorizer API Gateway davanti al server locale, quindi fornisci un’identità stub per lo sviluppo locale:

const httpResponse = await serviceHandler.handle(httpRequest, {
  tracer,
  logger,
  metrics,
  getIdentity: async () => ({ sub: 'local', username: 'local' }),
});

Ora possiamo utilizzare l’identità risolta in un’operazione, ad esempio in src/operations/echo.ts:

import { ServiceContext } from '../context.js';
import { Echo as EchoOperation } from '../generated/ssdk/index.js';


export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
  const identity = await ctx.getIdentity();
  return { message: `${identity.username} says ${input.message}` };
};

Building e Generazione del Codice

Sezione intitolata “Building e Generazione del Codice”

Il progetto del modello Smithy utilizza la Smithy CLI per costruire gli artefatti Smithy e generare il TypeScript Server SDK:

Terminal window
pnpm nx build <model-project>

Su macOS e Linux la CLI viene risolta da mise, che la build recupera su richiesta, quindi non c’è nulla da installare — scarica e memorizza nella cache la versione fissata la prima volta che esegui la build.

Questo processo:

  1. Compila il modello Smithy e lo valida
  2. Genera la specifica OpenAPI dal modello Smithy
  3. Crea il TypeScript Server SDK con interfacce di operazione type-safe
  4. Produce artefatti di build in dist/<model-project>/build/

Il progetto backend copia automaticamente l’SDK generato durante la compilazione:

Terminal window
pnpm nx copy-ssdk <backend-project>

Building su Windows

Sezione intitolata “Building su Windows”

mise non pubblica alcun pacchetto Windows su npm, quindi su Windows la Smithy CLI è un prerequisito che installi tu stesso. Installala una volta seguendo la guida all’installazione della Smithy CLI (ad esempio winget install smithy o scoop install smithy), e assicurati che smithy sia nel tuo PATH. Un progetto Smithy generato su Windows esegue smithy direttamente piuttosto che attraverso mise.

In alternativa, sviluppa all’interno di WSL, dove la build esegue il percorso Linux e mise risolve la CLI per te — nulla da installare.

Un progetto generato su Windows esegue il commit di un target compile che invoca smithy direttamente, quindi chiunque altro ci lavori — incluso su macOS o Linux — ha bisogno della Smithy CLI nel proprio PATH anche. Per far sì che quelle macchine risolvano la CLI attraverso mise invece, cambia il target al comando mise come descritto di seguito.

Scegliere come viene risolta la CLI

Sezione intitolata “Scegliere come viene risolta la CLI”

macOS e Linux risolvono la CLI attraverso mise e Windows utilizza una CLI installata globalmente, ma puoi scegliere una delle due su qualsiasi piattaforma modificando il comando del target compile nel project.json del progetto del modello.

Per utilizzare una Smithy CLI installata globalmente invece di mise, sostituisci il prefisso mise con un semplice smithy:

project.json
{
  "targets": {
    "compile": {
      "options": {
        "commands": ["... npx -y mise@<version> exec smithy@<version> -- smithy build ..."]
        "commands": ["... smithy build ..."]
      }
    }
  }
}

Per tornare a far risolvere la CLI da mise, ripristina il prefisso npx -y mise@<version> exec smithy@<version> --.

Target Bundle

Sezione intitolata “Target Bundle”

Il generatore configura automaticamente un target bundle che utilizza Rolldown per creare un pacchetto di distribuzione:

Terminal window
pnpm nx bundle <project-name>

La configurazione di Rolldown si trova in rolldown.config.ts, con una voce per ogni bundle da generare. Rolldown gestisce la creazione di più bundle in parallelo se definiti.

Sviluppo Locale

Sezione intitolata “Sviluppo Locale”

Il generatore configura un server di sviluppo locale con hot reloading:

Terminal window
pnpm nx serve <backend-project>

Distribuire la tua Smithy API

Sezione intitolata “Distribuire la tua Smithy API”

Il generatore crea infrastruttura CDK o Terraform in base al tuo iac selezionato.

Il costrutto CDK per distribuire la tua API si trova nella cartella common/constructs:

import { MyApi } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the API to your stack
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Questo configura:

  1. Una funzione AWS Lambda per il servizio Smithy
  2. API Gateway REST API come trigger della funzione
  3. Ruoli IAM e permessi
  4. Gruppo di log CloudWatch
  5. Configurazione del tracing X-Ray
auth = cognito
auth = custom

WAF

Sezione intitolata “WAF”

Per le REST API, il costrutto generato associa un Web ACL AWS WAFv2 allo stage di API Gateway per impostazione predefinita. Il Web ACL utilizza il set di regole predefinito gestito da AWS (AWSManagedRulesCommonRuleSet e AWSManagedRulesKnownBadInputsRuleSet), fornendo protezione contro exploit web comuni inclusa la OWASP Top 10. I log delle richieste WAF vengono scritti in un gruppo di CloudWatch Logs.

Puoi modificare il costrutto rest-api generato per aggiungere, rimuovere o regolare le regole (ad esempio, per aggiungere regole basate sulla frequenza o gruppi di regole gestite aggiuntivi).

Per disattivare (ad esempio, per collegare il tuo Web ACL), imposta enableWaf su false:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
  enableWaf: false,
});

Logging degli accessi

Sezione intitolata “Logging degli accessi”

Per le REST API, l’infrastruttura generata abilita la registrazione degli accessi per impostazione predefinita, scrivendo una riga JSON strutturata per richiesta in un gruppo CloudWatch Logs dedicato. Il gruppo di log è crittografato con una chiave KMS gestita dal cliente e conservato per un anno.

API Gateway scrive i log di accesso utilizzando un ruolo CloudWatch Logs a livello di account. Questo ruolo è configurato sull’impostazione AWS::ApiGateway::Account, che è un singleton per regione per account — esiste un solo ruolo per ogni REST API nella regione. Per gestire questo in modo sicuro tra più stack distribuiti indipendentemente, l’infrastruttura generata:

  • Crea un ruolo CloudWatch Logs condiviso e lo configura sull’account solo quando non è già impostato un ruolo funzionante, in modo che le distribuzioni non sovrascrivano mai un ruolo di proprietà di un altro stack.
  • Lascia intatta l’impostazione dell’account durante lo smantellamento, in modo che la distruzione di uno stack non disabiliti mai la registrazione per altre REST API nella regione.

Il ruolo dell’account è gestito dal costrutto ApiGatewayAccount, un singleton con ambito stack risolto tramite ApiGatewayAccount.ensure(scope). Ogni stage della REST API dipende da esso e il ruolo è configurato da una risorsa personalizzata supportata da Lambda.

Il formato del log di accesso è impostato dal costrutto RestApi che la tua API estende. Per personalizzarlo, passa deployOptions a super nel file generato packages/common/constructs/src/app/apis/my-api.ts, mantenendo il tracingEnabled che il costrutto già imposta:

packages/common/constructs/src/app/apis/my-api.ts
super(scope, id, {
  apiName: 'MyApi',
  // ...
  deployOptions: {
    tracingEnabled: true,
    accessLogFormat: AccessLogFormat.clf(),
  },
  ...props,
});

AccessLogFormat è importato da aws-cdk-lib/aws-apigateway. Tutto ciò che lasci non impostato mantiene il valore predefinito del costrutto — un formato JSON con i campi standard.

Integrazioni

Sezione intitolata “Integrazioni”

I costrutti CDK REST/HTTP API sono configurati per fornire un’interfaccia type-safe per definire integrazioni per ciascuna delle tue operazioni.

Integrazioni Predefinite

Sezione intitolata “Integrazioni Predefinite”

Puoi utilizzare il metodo statico defaultIntegrations per utilizzare il pattern predefinito, che definisce una funzione AWS Lambda individuale per ogni operazione:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});

Accesso alle Integrazioni

Sezione intitolata “Accesso alle Integrazioni”

Puoi accedere alle funzioni AWS Lambda sottostanti tramite la proprietà integrations del costrutto API, in modo type-safe. Ad esempio, se la tua API definisce un’operazione chiamata sayHello e devi aggiungere alcune autorizzazioni a questa funzione, puoi farlo come segue:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});


// sayHello is typed to the operations defined in your API
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Se la tua API utilizza il pattern shared, il router Lambda condiviso è esposto come api.integrations.$router:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this).build(),
});


api.integrations.$router.handler.addEnvironment('LOG_LEVEL', 'DEBUG');

Nota che $router non è più disponibile se sovrascrivi ogni operazione tramite withOverrides, poiché nessuna operazione rimane ad utilizzare l’integrazione router predefinita.

Personalizzazione delle Opzioni Predefinite

Sezione intitolata “Personalizzazione delle Opzioni Predefinite”

Se desideri personalizzare le opzioni utilizzate durante la creazione della funzione Lambda per ogni integrazione predefinita, puoi utilizzare il metodo withDefaultOptions. Ad esempio, se desideri che tutte le tue funzioni Lambda risiedano in un Vpc:

const vpc = new Vpc(this, 'Vpc', ...);


new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withDefaultOptions({
      vpc,
    })
    .build(),
});

Personalizzazione delle Opzioni per Operazione

Sezione intitolata “Personalizzazione delle Opzioni per Operazione”

Per personalizzare le opzioni utilizzate per creare l’integrazione predefinita per operazioni specifiche (senza influenzare le altre), puoi utilizzare il metodo withOperationOptions. Ad esempio, se desideri aumentare il timeout della funzione Lambda solo per un’operazione:

const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOperationOptions({
      sayHello: {
        timeout: Duration.seconds(60),
      },
    })
    .build(),
});


// The selected operations remain default integrations, so they're still typed accordingly:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Le opzioni che specifichi vengono unite alle opzioni di integrazione predefinite (e a qualsiasi opzione impostata tramite withDefaultOptions). Nota che non puoi specificare opzioni per operazioni che hai sostituito tramite withOverrides, poiché queste non utilizzano più l’integrazione predefinita.

Incontrerai un errore di tipo se la stessa operazione è targetizzata sia da withOperationOptions che da withOverrides, indipendentemente dall’ordine in cui li chiami.

Override delle Integrazioni

Sezione intitolata “Override delle Integrazioni”

Puoi anche sovrascrivere le integrazioni per operazioni specifiche utilizzando il metodo withOverrides. Ogni override deve specificare una proprietà integration che è tipizzata al costrutto di integrazione CDK appropriato per l’API HTTP o REST. Il metodo withOverrides è anche type-safe. Ad esempio, se desideri sovrascrivere un’API getDocumentation per puntare alla documentazione ospitata da un sito web esterno, potresti ottenere questo come segue:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
      },
    })
    .build(),
});

Noterai anche che l’integrazione sovrascritta non ha più una proprietà handler quando vi accedi tramite api.integrations.getDocumentation.

Puoi aggiungere proprietà aggiuntive a un’integrazione che saranno anche tipizzate di conseguenza, consentendo ad altri tipi di integrazione di essere astratti ma rimanere type-safe, ad esempio se hai creato un’integrazione S3 per un’API REST e successivamente desideri fare riferimento al bucket per una particolare operazione, puoi farlo come segue:

const storageBucket = new Bucket(this, 'Bucket', { ... });


const apiGatewayRole = new Role(this, 'ApiGatewayS3Role', {
  assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
});


storageBucket.grantRead(apiGatewayRole);


const api = new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getFile: {
        bucket: storageBucket,
        integration: new AwsIntegration({
          service: 's3',
          integrationHttpMethod: 'GET',
          path: `${storageBucket.bucketName}/{fileName}`,
          options: {
            credentialsRole: apiGatewayRole,
            requestParameters: {
              'integration.request.path.fileName': 'method.request.querystring.fileName',
            },
            integrationResponses: [{ statusCode: '200' }],
          },
        }),
        options: {
          requestParameters: {
            'method.request.querystring.fileName': true,
          },
          methodResponses: [{
            statusCode: '200',
          }],
        }
      },
    })
    .build(),
});


// Later, perhaps in another file, you can access the bucket property we defined
// in a type-safe manner
api.integrations.getFile.bucket.grantRead(...);

Override degli Authorizer

Sezione intitolata “Override degli Authorizer”

Puoi anche fornire options nella tua integrazione per sovrascrivere particolari opzioni del metodo come gli authorizer, ad esempio se desideri utilizzare l’autenticazione Cognito per la tua operazione getDocumentation:

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
        options: {
          authorizer: new CognitoUserPoolsAuthorizer(...) // for REST, or HttpUserPoolAuthorizer for an HTTP API
        }
      },
    })
    .build(),
});

Integrazioni Esplicite

Sezione intitolata “Integrazioni Esplicite”

Se preferisci, puoi scegliere di non utilizzare le integrazioni predefinite e invece fornirne direttamente una per ogni operazione. Questo è utile se, ad esempio, ogni operazione deve utilizzare un tipo diverso di integrazione o desideri ricevere un errore di tipo quando aggiungi nuove operazioni:

new MyApi(this, 'MyApi', {
  integrations: {
    sayHello: {
      integration: new LambdaIntegration(...),
    },
    getDocumentation: {
      integration: new HttpIntegration(...),
    },
  },
});

Pattern di Integrazione

Sezione intitolata “Pattern di Integrazione”

Le API generate supportano due pattern di integrazione:

  • isolated crea una funzione Lambda per operazione. Questa è l’opzione predefinita e consigliata per le API.
  • shared crea un singolo router Lambda predefinito e lo riutilizza per ogni operazione a meno che non si sovrascrivano integrazioni specifiche.

isolated ti offre autorizzazioni e configurazione più granulari per operazione, oltre a una migliore separazione per log e tracce. shared riduce la probabilità di incontrare cold-start per API a basso utilizzo.

Il pattern di integrazione può essere modificato in qualsiasi momento in CDK aggiornando il tuo costrutto API. Ad esempio, impostando pattern su 'shared' si crea una singola funzione invece di una per integrazione:

packages/common/constructs/src/app/apis/my-api.ts
export class MyApi<...> extends ... {


  public static defaultIntegrations = (scope: Construct) => {
    ...
    return IntegrationBuilder.rest({
      pattern: 'shared',
      ...
    });
  };
}
iac = terraform, infra = rest-lambda
Terraform REST API Path Depth Limit
Sezione intitolata “Terraform REST API Path Depth Limit”

Generazione del Codice

Sezione intitolata “Generazione del Codice”

Poiché le operazioni sono definite in Smithy, utilizziamo la generazione del codice per fornire metadati al costrutto CDK per integrazioni type-safe.

Un target generate:<ApiName>-metadata viene aggiunto al project.json dei costrutti comuni per facilitare questa generazione del codice, che emette un file come packages/common/constructs/src/generated/my-api/metadata.gen.ts. Poiché questo viene generato al momento della build, viene ignorato nel controllo di versione.

auth = iam

Concedere l’Accesso (Solo IAM)

Sezione intitolata “Concedere l’Accesso (Solo IAM)”

Se hai selezionato l’autenticazione IAM, puoi utilizzare il metodo grantInvokeAccess per concedere l’accesso alla tua API:

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Invocare la tua Smithy API

Sezione intitolata “Invocare la tua Smithy API”

Per invocare la tua API da un sito web React, puoi utilizzare il generatore connection, che fornisce generazione di client type-safe dal tuo modello Smithy.

Connessioni

Sezione intitolata “Connessioni”

Utilizza il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

Smithy
React a Smithy APIChiamare un'API Smithy da un sito web React
SmithyAmazon Aurora
Smithy API a Database RelazionaleConnettere un'API Smithy a un database relazionale Aurora
SmithyAmazon DynamoDB
Smithy API a TypeScript DynamoDBConnettere un'API Smithy a una tabella DynamoDB