Skip to content
@aws/nx-plugin
Blog

Smithy TypeScriptのAPI

Filter this guidePick generator option values to hide sections that don't apply.

Smithyはプロトコルに依存しないインターフェース定義言語で、モデル駆動のアプローチでAPIを設計できます。

Smithy TypeScript APIジェネレータは、サービス定義にSmithyを、実装にSmithy TypeScript Server SDKを使用した新しいAPIを作成します。このジェネレータはCDKまたはTerraformのInfrastructure as Codeを提供し、AWS LambdaにデプロイされたサービスをAWS API Gateway REST API経由で公開します。Smithyモデルからの自動コード生成により、型安全なAPI開発を実現します。生成されたハンドラはAWS Lambda Powertools for TypeScriptを使用し、ロギング、AWS X-Rayトレーシング、CloudWatchメトリクスなどの観測可能性を備えています。

使用方法

Section titled “使用方法”

Smithy TypeScript APIの生成

Section titled “Smithy TypeScript APIの生成”

新しいSmithy TypeScript APIは2つの方法で生成できます：

  1. インストール Nx Console VSCode Plugin まだインストールしていない場合
  2. VSCodeでNxコンソールを開く
  3. クリック Generate (UI) "Common Nx Commands"セクションで
  4. 検索 @aws/nx-plugin - ts#api
  5. 必須パラメータを入力
    • framework: smithy
  6. クリック Generate

オプション

Section titled “オプション”
パラメータ型デフォルト説明
name 必須string-APIの名前（必須）。クラス名とファイルパスの生成に使用されます。
framework trpc | smithytrpc使用するAPIフレームワーク。
namespace string-Smithy APIの名前空間（smithyフレームワークにのみ適用されます）。デフォルトはモノレポのスコープです
integrationPattern isolated | sharedisolatedAPI用にAPI Gateway統合を生成する方法。isolated（デフォルト）またはsharedから選択します。
auth iam | cognito | customiamAPIの認証に使用する方法。iam（デフォルト）、cognito、customから選択します。
directory stringpackagesアプリケーションを保存するディレクトリ。
subDirectory string-プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
iac inherit | cdk | terraforminherit優先するIaCプロバイダー。デフォルトでは初期選択から継承されます。
infra rest-lambda | http-lambda | nonerest-lambdaこのAPIをデプロイするために使用するインフラストラクチャのタイプ。
preferInstallDependencies booleantrueジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合は false に設定します（後続のジェネレーターが Nx プロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレータの出力

Section titled “ジェネレータの出力”

ジェネレータは<directory>/<api-name>ディレクトリに2つの関連プロジェクトを作成します：

  • Directorymodel/ Smithyモデルプロジェクト
    • project.json プロジェクト設定とビルドターゲット
    • smithy-build.json Smithyビルド設定
    • build.Dockerfile Smithyアーティファクトビルド用Docker設定
    • Directorysrc/
      • main.smithy メインサービス定義
      • Directoryoperations/
        • echo.smithy オペレーション定義例
  • Directorybackend/ TypeScriptバックエンド実装
    • project.json プロジェクト設定とビルドターゲット
    • rolldown.config.ts バンドル設定
    • Directorysrc/
      • handler.ts AWS Lambdaハンドラ
      • local-server.ts ローカル開発サーバ
      • service.ts サービス実装
      • context.ts サービスコンテキスト定義
      • Directoryoperations/
        • echo.ts オペレーション実装例
      • Directorygenerated/ 生成されたTypeScript SDK（ビルド時に作成）
        • …

インフラストラクチャ

Section titled “インフラストラクチャ”

このジェネレータは選択したiacProviderに基づいたInfrastructure as Codeを作成するため、packages/commonにCDKコンストラクトまたはTerraformモジュールを含むプロジェクトを生成します。

共通のInfrastructure as Codeプロジェクトの構造は以下の通りです：

  • Directorypackages/common/constructs
    • Directorysrc
      • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト
        • Directoryapis/
          • <project-name>.ts APIデプロイ用CDKコンストラクト
      • Directorycore/ 再利用可能な汎用コンストラクト
        • Directoryapi/
          • rest-api.ts REST APIデプロイ用コンストラクト
          • utils.ts APIコンストラクト用ユーティリティ
      • index.ts コンストラクトエクスポート用エントリポイント
    • project.json プロジェクトビルドターゲットと設定

アーキテクチャ

Section titled “アーキテクチャ”

デプロイされたSmithy APIは以下のアーキテクチャを持ち、API Gatewayステージの前にAWS WAFv2 Web ACLが配置されます：

ClientWAFAPI Gateway(REST API)Lambda(Smithy Server SDK)CloudWatch(Logs, Metrics)X-Ray(Traces)

Smithy APIの実装

Section titled “Smithy APIの実装”

Smithyでのオペレーション定義

Section titled “Smithyでのオペレーション定義”

オペレーションはモデルプロジェクト内のSmithyファイルで定義されます。メインサービス定義は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,
        // オペレーションを追加
    ]
    errors: [
        ValidationException
    ]
}

個々のオペレーションは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
}

TypeScriptでのオペレーション実装

Section titled “TypeScriptでのオペレーション実装”

オペレーション実装はバックエンドプロジェクトのsrc/operations/ディレクトリに配置されます。各オペレーションはSmithyモデルからビルド時に生成されるTypeScript Server SDKの型を使用して実装されます。

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


export const Echo: EchoOperation<ServiceContext> = async (input) => {
  // ビジネスロジックを実装
  return {
    message: `Echo: ${input.message}` // Smithyモデルに基づく型安全
  };
};

オペレーションはsrc/service.tsでサービス定義に登録する必要があります：

import { ServiceContext } from './context.js';
import { YourServiceService } from './generated/ssdk/index.js';
import { Echo } from './operations/echo.js';
// 他のオペレーションをインポート


// サービスにオペレーションを登録
export const Service: YourServiceService<ServiceContext> = {
  Echo,
  // 他のオペレーションを追加
};

サービスコンテキスト

Section titled “サービスコンテキスト”

context.tsでオペレーション間で共有するコンテキストを定義できます：

export interface ServiceContext {
  // PowertoolsのTracer、Logger、Metricsがデフォルトで提供
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  // 共有依存関係、データベース接続などを追加
  dbClient: any;
  userIdentity: string;
}

このコンテキストはすべてのオペレーション実装に渡され、データベース接続や設定、ロギングユーティリティなどのリソース共有に使用できます。

AWS Lambda Powertoolsによる観測可能性

Section titled “AWS Lambda Powertoolsによる観測可能性”

ロギング

Section titled “ロギング”

ジェネレータはMiddyミドルウェア経由で自動コンテキスト注入されるAWS Lambda Powertoolsを使用した構造化ロギングを設定します。

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

オペレーション実装でコンテキストからロガーを参照できます：

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('ログメッセージ');
  // ...
};

トレーシング

Section titled “トレーシング”

AWS X-RayトレーシングはcaptureLambdaHandlerミドルウェアで自動設定されます。

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

オペレーション内でカスタムサブセグメントをトレースに追加できます：

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 subsegment = ctx.tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // ロジックを実装
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

メトリクス

Section titled “メトリクス”

CloudWatchメトリクスはlogMetricsミドルウェアを介して各リクエストで自動収集されます。

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

オペレーション内でカスタムメトリクスを追加できます：

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);
  // ...
};

エラーハンドリング

Section titled “エラーハンドリング”

Smithyは組み込みのエラーハンドリングを提供します。カスタムエラーはSmithyモデルで定義できます：

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

オペレーション/サービスに登録：

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

TypeScript実装でスロー：

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


export const MyOperation: MyOperationHandler<ServiceContext> = async (input) => {
  if (!input.requiredField) {
    throw new InvalidRequestError({
      message: "必須フィールドが不足しています"
    });
  }


  return { /* 成功レスポンス */ };
};

呼び出しユーザーへのアクセス

Section titled “呼び出しユーザーへのアクセス”

APIが認証で保護されている場合、オペレーションは誰が呼び出しているかを知る必要があることがよくあります。推奨されるアプローチは、ハンドラーで一度呼び出し元のIDを解決し、サービスコンテキストを通じて渡して、特定のオペレーションで使用できるようにすることです。

未認証のケースをSmithyエラーとしてモデル化し、適切な403レスポンスにシリアライズされるようにします。モデルに追加します。例えばmodel/src/operations/errors.smithyに追加し、IDを必要とする任意のオペレーションで参照します：

$version: "2.0"


namespace your.namespace


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

まず、src/context.tsでサービスコンテキストに解決されたIDを公開します。UnauthorizedErrorがハンドラーからではなく、オペレーション内から（Server SDKが403にシリアライズする場所で）スローされるように、関数として提供します：

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>;
}

次に、src/identity.tsでリゾルバーを記述します。呼び出し元を特定できない場合はUnauthorizedErrorをスローします。実装は選択したauthメソッドによって異なります：

auth = iam

IAM認証の場合、API Gatewayイベントから抽出したsubを使用してCognitoで呼び出し元を検索します：

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

auth: 'cognito'の場合、API Gateway Cognito User Pools オーソライザーは、呼び出し元がAuthorizationヘッダーで提供するJWTを検証し、検証済みのクレームを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 };
};

次に、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),
});

これで、オペレーション内で解決されたIDを使用できます。例えば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}` };
};

ビルドとコード生成

Section titled “ビルドとコード生成”

SmithyモデルプロジェクトはDockerを使用してSmithyアーティファクトをビルドし、TypeScript Server SDKを生成します：

Terminal window
pnpm nx build <model-project>

このプロセスでは：

  1. Smithyモデルのコンパイルと検証
  2. SmithyモデルからのOpenAPI仕様の生成
  3. 型安全なオペレーションインターフェースを含むTypeScript Server SDKの作成
  4. ビルドアーティファクトの出力をdist/<model-project>/build/に配置

バックエンドプロジェクトはコンパイル時に生成されたSDKを自動コピーします：

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

バンドルターゲット

Section titled “バンドルターゲット”

ジェネレーターは自動的に Rolldown を使用する bundle ターゲットを設定します。このターゲットはデプロイメントパッケージの作成に使用されます：

Terminal window
pnpm nx bundle <project-name>

Rolldownの設定はrolldown.config.tsに記述され、生成するバンドルごとにエントリを定義します。Rolldownは定義された複数のバンドルを並行して作成する処理を管理します。

ローカル開発

Section titled “ローカル開発”

ジェネレータはホットリロード機能を備えたローカル開発サーバを設定します：

Terminal window
pnpm nx serve <backend-project>

Smithy APIのデプロイ

Section titled “Smithy APIのデプロイ”

ジェネレータは選択したiacProviderに基づいてCDKまたはTerraformインフラストラクチャを作成します。

APIデプロイ用CDKコンストラクトはcommon/constructsフォルダにあります：

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


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // APIをスタックに追加
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

これにより以下が設定されます：

  1. Smithyサービス用AWS Lambda関数
  2. API Gateway REST APIトリガー
  3. IAMロールと権限
  4. CloudWatchロググループ
  5. X-Rayトレーシング設定
auth = cognito

WAF

Section titled “WAF”

REST APIの場合、生成されたコンストラクトはデフォルトでAWS WAFv2 Web ACLをAPI Gatewayステージに関連付けます。Web ACLはAWSマネージドデフォルトルールセット（AWSManagedRulesCommonRuleSetおよびAWSManagedRulesKnownBadInputsRuleSet）を使用し、OWASP Top 10を含む一般的なWebエクスプロイトに対する保護を提供します。WAFリクエストログはCloudWatch Logsグループに書き込まれます。

生成されたrest-apiコンストラクトを編集して、ルールを追加、削除、または調整できます（例えば、レートベースルールや追加のマネージドルールグループを追加する場合など）。

オプトアウトする場合（例えば、独自のWeb ACLをアタッチする場合）、enableWafをfalseに設定します：

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

アクセスログ

Section titled “アクセスログ”

REST APIの場合、生成されたインフラストラクチャはデフォルトでアクセスログを有効にし、リクエストごとに1行の構造化されたJSONを専用のCloudWatch Logsグループに書き込みます。ログループは顧客管理のKMSキーで暗号化され、1年間保持されます。

API Gatewayは、アカウントレベルのCloudWatch Logsロールを使用してアクセスログを書き込みます。このロールはAWS::ApiGateway::Account設定で構成されており、これはリージョンごと、アカウントごとのシングルトンです。つまり、リージョン内のすべてのREST APIに対して1つのロールしか存在しません。独立してデプロイされる複数のスタック間でこれを安全に管理するため、生成されたインフラストラクチャは次のようになっています：

  • 共有CloudWatch Logsロールを作成し、動作中のロールがまだ設定されていない場合にのみアカウントに構成するため、デプロイメントが他のスタックが所有するロールを上書きすることはありません。
  • 破棄時にアカウント設定をそのままにするため、1つのスタックを破棄してもリージョン内の他のREST APIのログ記録が無効になることはありません。

アカウントロールはApiGatewayAccountコンストラクトによって管理されます。これはApiGatewayAccount.ensure(scope)を介して解決されるスタックスコープのシングルトンです。各REST APIのステージはこれに依存しており、ロールはLambdaベースのカスタムリソースによって構成されます。

APIを構築する際にdeployOptionsを渡すことで、アクセスログ形式をカスタマイズできます：

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

インテグレーション

Section titled “インテグレーション”

REST/HTTP API CDKコンストラクトは、各オペレーションの統合を定義するための型安全なインターフェースを提供するように設定されています。

CDKコンストラクトは、以下で説明する完全な型安全な統合サポートを提供します。

デフォルト統合

Section titled “デフォルト統合”

静的メソッドdefaultIntegrationsを使用して、各オペレーションに個別のAWS Lambda関数を定義するデフォルトパターンを利用できます：

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

統合へのアクセス

Section titled “統合へのアクセス”

APIコンストラクトのintegrationsプロパティを通じて、型安全な方法で基盤となるAWS Lambda関数にアクセスできます。例えば、APIがsayHelloというオペレーションを定義している場合、この関数に権限を追加するには次のようにします：

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


// sayHelloはAPIで定義されたオペレーションに型付けされます
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

APIがsharedパターンを使用している場合、共有ルーターLambdaはapi.integrations.$routerとして公開されます：

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


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

デフォルトオプションのカスタマイズ

Section titled “デフォルトオプションのカスタマイズ”

デフォルト統合で作成されるLambda関数のオプションをカスタマイズするには、withDefaultOptionsメソッドを使用します。例えば、すべてのLambda関数をVPC内に配置する場合：

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


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

オペレーションごとのオプションのカスタマイズ

Section titled “オペレーションごとのオプションのカスタマイズ”

_特定の_オペレーションのデフォルト統合を作成する際に使用するオプションをカスタマイズするには（他のオペレーションに影響を与えずに）、withOperationOptionsメソッドを使用します。例えば、1つのオペレーションだけLambda関数のタイムアウトを増やす場合：

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


// 選択されたオペレーションはデフォルト統合のままなので、それに応じて型付けされます：
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

指定したオプションはデフォルト統合オプション（およびwithDefaultOptionsで設定したオプション）とマージされます。withOverridesで置き換えたオペレーションにはオプションを指定できないことに注意してください。これらはもはやデフォルト統合を使用しないためです。

同じオペレーションがwithOperationOptionsとwithOverridesの両方でターゲットにされている場合、呼び出す順序に関係なく型エラーが発生します。

統合のオーバーライド

Section titled “統合のオーバーライド”

withOverridesメソッドを使用して特定のオペレーションの統合をオーバーライドできます。各オーバーライドは、HTTPまたはREST APIに適したCDK統合コンストラクトに型付けされたintegrationプロパティを指定する必要があります。withOverridesメソッドも型安全です。例として、getDocumentation APIを外部サイトのドキュメントにポイントする場合：

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

オーバーライドされた統合は、api.integrations.getDocumentationでアクセスした際にhandlerプロパティを持たないことに注意してください。

追加プロパティを統合に追加することで、他のタイプの統合を抽象化しつつ型安全性を維持できます。例えば、REST API用にS3統合を作成し、後で特定のオペレーションでバケットを参照する場合：

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(),
});


// 後で別ファイルで、定義したbucketプロパティに
// 型安全にアクセスできます
api.integrations.getFile.bucket.grantRead(...);

オーソライザーのオーバーライド

Section titled “オーソライザーのオーバーライド”

統合にoptionsを指定して、特定のメソッドオプション（オーソライザーなど）をオーバーライドできます。例として、getDocumentationオペレーションにCognito認証を使用する場合：

new MyApi(this, 'MyApi', {
  integrations: MyApi.defaultIntegrations(this)
    .withOverrides({
      getDocumentation: {
        integration: new HttpIntegration('https://example.com/documentation'),
        options: {
          authorizer: new CognitoUserPoolsAuthorizer(...) // REST用、HTTP APIの場合はHttpUserPoolAuthorizer
        }
      },
    })
    .build(),
});

明示的統合

Section titled “明示的統合”

必要に応じて、デフォルト統合を使用せずに各オペレーションに直接統合を指定できます。例えば、オペレーションごとに異なる統合タイプを使用する場合や、新しいオペレーション追加時に型エラーを受け取りたい場合に有用です：

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

統合パターン

Section titled “統合パターン”

生成されたCDK APIコンストラクトは2つの統合パターンをサポートしています：

  • isolatedはオペレーションごとに1つのLambda関数を作成します。これが生成されたAPIのデフォルトです。
  • sharedは単一のデフォルトルーターLambdaを作成し、特定の統合をオーバーライドしない限りすべてのオペレーションで再利用します。

isolatedはオペレーションごとにきめ細かい権限と設定を提供します。sharedはLambdaとAPI Gateway統合の増殖を抑えつつ、選択的なオーバーライドを可能にします。

例えば、patternを'shared'に設定すると、統合ごとに1つではなく単一の関数を作成します：

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


  public static defaultIntegrations = (scope: Construct) => {
    ...
    return IntegrationBuilder.rest({
      pattern: 'shared',
      ...
    });
  };
}

コード生成

Section titled “コード生成”

オペレーションはSmithyで定義されるため、型安全なインテグレーションのためにCDKコンストラクトにメタデータを提供するコード生成を使用します。

共通コンストラクトのproject.jsonにgenerate:<ApiName>-metadataターゲットが追加され、packages/common/constructs/src/generated/my-api/metadata.gen.tsのようなファイルが生成されます。これはビルド時に生成されるため、バージョン管理から除外されます。

auth = iam

アクセス権限付与（IAMのみ）

Section titled “アクセス権限付与（IAMのみ）”

IAM認証を選択した場合、grantInvokeAccessメソッドでAPIへのアクセス権限を付与できます：

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Smithy APIの呼び出し

Section titled “Smithy APIの呼び出し”

ReactウェブサイトからAPIを呼び出すには、connectionジェネレータを使用できます。これはSmithyモデルから型安全なクライアントを生成します。 ��なクライアントを生成します。

接続

Section titled “接続”

connectionジェネレータを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合できます。このプロジェクトに関連する接続は以下の通りです：

Smithy
React to Smithy APIReactウェブサイトからSmithy APIを呼び出す
SmithyAmazon Aurora
Smithy API to Relational DatabaseSmithy APIをAuroraリレーショナルデータベースに接続する
SmithyAmazon DynamoDB
Smithy API to TypeScript DynamoDBSmithy APIをDynamoDBテーブルに接続する