Bỏ qua để đến nội dung
@aws/nx-plugin
Blog

API TypeScript của Smithy

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

Smithy là một ngôn ngữ định nghĩa giao diện độc lập với giao thức để tạo API theo cách hướng mô hình.

Trình tạo Smithy TypeScript API tạo một API mới sử dụng Smithy để định nghĩa dịch vụ, và Smithy TypeScript Server SDK để triển khai. Trình tạo cung cấp infrastructure as code bằng CDK hoặc Terraform để triển khai dịch vụ của bạn lên AWS Lambda, được truy cập thông qua AWS API Gateway REST API. Nó cung cấp phát triển API an toàn kiểu với tự động tạo mã từ mô hình Smithy. Handler được tạo sử dụng AWS Lambda Powertools for TypeScript cho khả năng quan sát, bao gồm logging, AWS X-Ray tracing và CloudWatch Metrics

Sử dụng

Phần tiêu đề “Sử dụng”

Tạo một Smithy TypeScript API

Phần tiêu đề “Tạo một Smithy TypeScript API”

Bạn có thể tạo một Smithy TypeScript API mới theo hai cách:

  1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
  2. Mở Nx Console trong VSCode
  3. Nhấp Generate (UI) trong phần "Common Nx Commands"
  4. Tìm kiếm @aws/nx-plugin - ts#api
  5. Điền các tham số bắt buộc
    • framework: smithy
  6. Nhấp Generate

Tùy chọn

Phần tiêu đề “Tùy chọn”
Tham sốKiểuMặc địnhMô tả
name Bắt buộcstring-Tên của API (bắt buộc). Được sử dụng để tạo tên class và đường dẫn file.
framework trpc | smithytrpcFramework API để sử dụng.
namespace string-Namespace cho Smithy API (chỉ áp dụng cho framework smithy). Mặc định là scope của monorepo
integrationPattern isolated | sharedisolatedCách thức tạo API Gateway integrations cho API. Chọn giữa isolated (mặc định) và shared.
auth iam | cognito | customiamPhương thức được sử dụng để xác thực với API của bạn. Chọn giữa iam (mặc định), cognito hoặc custom.
directory stringpackagesThư mục để lưu trữ ứng dụng.
subDirectory string-Thư mục con mà dự án được đặt trong đó. Mặc định đây là tên dự án.
iac inherit | cdk | terraforminheritNhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.
infra rest-lambda | http-lambda | nonerest-lambdaLoại hạ tầng được sử dụng để triển khai API này.
preferInstallDependencies booleantrueCó nên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Trình tạo

Phần tiêu đề “Kết quả của Trình tạo”

Trình tạo tạo hai dự án liên quan trong thư mục <directory>/<api-name>:

  • Thư mụcmodel/ Dự án mô hình Smithy
    • project.json Cấu hình dự án và build targets
    • smithy-build.json Cấu hình build Smithy
    • build.Dockerfile Cấu hình Docker để build các artifact Smithy
    • Thư mụcsrc/
      • main.smithy Định nghĩa dịch vụ chính
      • Thư mụcoperations/
        • echo.smithy Ví dụ định nghĩa operation
  • Thư mụcbackend/ Triển khai backend TypeScript
    • project.json Cấu hình dự án và build targets
    • rolldown.config.ts Cấu hình bundle
    • Thư mụcsrc/
      • handler.ts AWS Lambda handler
      • local-server.ts Server phát triển local
      • service.ts Triển khai dịch vụ
      • context.ts Định nghĩa context dịch vụ
      • Thư mụcoperations/
        • echo.ts Ví dụ triển khai operation
      • Thư mụcgenerated/ TypeScript SDK được tạo (tạo trong quá trình build)
        • …

Infrastructure

Phần tiêu đề “Infrastructure”

Vì trình tạo này tạo infrastructure as code dựa trên iacProvider bạn chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules tương ứng.

Dự án infrastructure as code chung được cấu trúc như sau:

  • Thư mụcpackages/common/constructs
    • Thư mụcsrc
      • Thư mụcapp/ Constructs cho infrastructure cụ thể cho một dự án/trình tạo
        • Thư mụcapis/
          • <project-name>.ts CDK construct để triển khai API của bạn
      • Thư mụccore/ Constructs chung được tái sử dụng bởi constructs trong app
        • Thư mụcapi/
          • rest-api.ts CDK construct để triển khai REST API
          • utils.ts Tiện ích cho API constructs
      • index.ts Entry point xuất các constructs từ app
    • project.json Build targets và cấu hình dự án

Kiến trúc

Phần tiêu đề “Kiến trúc”

Smithy API được triển khai có kiến trúc như sau, với AWS WAFv2 Web ACL đặt trước API Gateway stage:

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

Triển khai Smithy API của bạn

Phần tiêu đề “Triển khai Smithy API của bạn”

Định nghĩa Operations trong Smithy

Phần tiêu đề “Định nghĩa Operations trong Smithy”

Operations được định nghĩa trong các file Smithy trong dự án model. Định nghĩa dịch vụ chính nằm trong 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,
        // Thêm operations của bạn ở đây
    ]
    errors: [
        ValidationException
    ]
}

Các operations riêng lẻ được định nghĩa trong các file riêng biệt trong thư mục 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
}

Triển khai Operations trong TypeScript

Phần tiêu đề “Triển khai Operations trong TypeScript”

Các triển khai operation nằm trong thư mục src/operations/ của dự án backend. Mỗi operation được triển khai sử dụng các kiểu được tạo từ TypeScript Server SDK (được tạo tại thời điểm build từ mô hình Smithy của bạn).

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


export const Echo: EchoOperation<ServiceContext> = async (input) => {
  // Logic nghiệp vụ của bạn ở đây
  return {
    message: `Echo: ${input.message}` // an toàn kiểu dựa trên mô hình Smithy của bạn
  };
};

Operations phải được đăng ký vào định nghĩa dịch vụ trong src/service.ts:

import { ServiceContext } from './context.js';
import { YourServiceService } from './generated/ssdk/index.js';
import { Echo } from './operations/echo.js';
// Import các operations khác ở đây


// Đăng ký operations vào dịch vụ ở đây
export const Service: YourServiceService<ServiceContext> = {
  Echo,
  // Thêm các operations khác ở đây
};

Service Context

Phần tiêu đề “Service Context”

Bạn có thể định nghĩa context được chia sẻ cho các operations của bạn trong context.ts:

export interface ServiceContext {
  // Powertools tracer, logger và metrics được cung cấp mặc định
  tracer: Tracer;
  logger: Logger;
  metrics: Metrics;
  // Thêm các dependencies được chia sẻ, kết nối database, v.v.
  dbClient: any;
  userIdentity: string;
}

Context này được truyền cho tất cả các triển khai operation và có thể được sử dụng để chia sẻ tài nguyên như kết nối database, cấu hình, hoặc tiện ích logging.

Khả năng quan sát với AWS Lambda Powertools

Phần tiêu đề “Khả năng quan sát với AWS Lambda Powertools”

Logging

Phần tiêu đề “Logging”

Trình tạo cấu hình structured logging sử dụng AWS Lambda Powertools với tự động inject context thông qua Middy middleware.

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

Bạn có thể tham chiếu logger từ các triển khai operation của bạn thông qua context:

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('Thông điệp log của bạn');
  // ...
};

Tracing

Phần tiêu đề “Tracing”

AWS X-Ray tracing được cấu hình tự động thông qua middleware captureLambdaHandler.

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

Bạn có thể thêm subsegments tùy chỉnh vào traces của bạn trong các operations:

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) => {
  // Tạo một subsegment mới
  const subsegment = ctx.tracer.getSegment()?.addNewSubsegment('custom-operation');
  try {
    // Logic của bạn ở đây
  } catch (error) {
    subsegment?.addError(error as Error);
    throw error;
  } finally {
    subsegment?.close();
  }
};

Metrics

Phần tiêu đề “Metrics”

CloudWatch metrics được thu thập tự động cho mỗi request thông qua middleware logMetrics.

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

Bạn có thể thêm custom metrics trong các operations của bạn:

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

Xử lý Lỗi

Phần tiêu đề “Xử lý Lỗi”

Smithy cung cấp xử lý lỗi tích hợp sẵn. Bạn có thể định nghĩa các lỗi tùy chỉnh trong mô hình Smithy của bạn:

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

Và đăng ký chúng vào operation/service của bạn:

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

Sau đó ném chúng trong triển khai TypeScript của bạn:

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


export const MyOperation: MyOperationHandler<ServiceContext> = async (input) => {
  if (!input.requiredField) {
    throw new InvalidRequestError({
      message: "Trường bắt buộc bị thiếu"
    });
  }


  return { /* phản hồi thành công */ };
};

Truy Cập Người Dùng Đang Gọi

Phần tiêu đề “Truy Cập Người Dùng Đang Gọi”

Khi API của bạn được bảo vệ bằng xác thực, các operation thường cần biết ai đang gọi. Cách tiếp cận được khuyến nghị là giải quyết danh tính của người gọi một lần trong handler và truyền nó qua service context để các operation cụ thể sử dụng.

Chúng ta sẽ mô hình hóa trường hợp không được ủy quyền như một lỗi Smithy để nó được tuần tự hóa thành phản hồi 403 phù hợp. Thêm nó vào mô hình của bạn, ví dụ trong model/src/operations/errors.smithy, và tham chiếu nó trên bất kỳ operation nào yêu cầu danh tính:

$version: "2.0"


namespace your.namespace


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

Đầu tiên, hiển thị danh tính đã giải quyết trên service context trong src/context.ts. Chúng ta cung cấp nó dưới dạng một hàm để UnauthorizedError được ném ra từ bên trong một operation (nơi Server SDK tuần tự hóa nó thành 403), thay vì từ 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>;
}

Tiếp theo, viết resolver trong src/identity.ts. Nó ném UnauthorizedError khi không thể xác định người gọi. Cách triển khai phụ thuộc vào phương thức auth đã chọn:

auth = iam

Đối với xác thực IAM, chúng ta tra cứu người gọi trong Cognito bằng cách sử dụng sub được trích xuất từ sự kiện API Gateway:

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

Với auth: 'cognito', trình ủy quyền Cognito User Pools của API Gateway xác minh JWT mà người gọi cung cấp trong header Authorization và đặt các claim đã xác minh trên sự kiện tại 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 };
};

Sau đó kết nối resolver vào context trong 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),
});

Bây giờ chúng ta có thể sử dụng danh tính đã giải quyết trong một operation, ví dụ trong 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 và Tạo Mã

Phần tiêu đề “Building và Tạo Mã”

Dự án mô hình Smithy sử dụng Docker để build các artifact Smithy và tạo TypeScript Server SDK:

Terminal window
pnpm nx build <model-project>

Quá trình này:

  1. Biên dịch mô hình Smithy và xác thực nó
  2. Tạo đặc tả OpenAPI từ mô hình Smithy
  3. Tạo TypeScript Server SDK với các giao diện operation an toàn kiểu
  4. Xuất các build artifacts ra dist/<model-project>/build/

Dự án backend tự động sao chép SDK được tạo trong quá trình biên dịch:

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

Bundle Target

Phần tiêu đề “Bundle Target”

Generator tự động cấu hình một target bundle sử dụng Rolldown để tạo gói triển khai:

Terminal window
pnpm nx bundle <project-name>

Cấu hình Rolldown có thể được tìm thấy trong rolldown.config.ts, với một entry cho mỗi bundle cần tạo. Rolldown quản lý việc tạo nhiều bundle song song nếu được định nghĩa.

Phát triển Local

Phần tiêu đề “Phát triển Local”

Trình tạo cấu hình một server phát triển local với hot reloading:

Terminal window
pnpm nx serve <backend-project>

Triển khai Smithy API của bạn

Phần tiêu đề “Triển khai Smithy API của bạn”

Trình tạo tạo infrastructure CDK hoặc Terraform dựa trên iacProvider bạn đã chọn.

CDK construct để triển khai API của bạn nằm trong thư mục common/constructs:

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


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Thêm API vào stack của bạn
    const api = new MyApi(this, 'MyApi', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

Điều này thiết lập:

  1. Một AWS Lambda function cho dịch vụ Smithy
  2. API Gateway REST API làm trigger cho function
  3. IAM roles và permissions
  4. CloudWatch log group
  5. Cấu hình X-Ray tracing
auth = cognito

WAF

Phần tiêu đề “WAF”

Đối với REST API, construct được tạo ra sẽ liên kết một AWS WAFv2 Web ACL với API Gateway stage theo mặc định. Web ACL sử dụng bộ quy tắc mặc định được quản lý bởi AWS (AWSManagedRulesCommonRuleSet và AWSManagedRulesKnownBadInputsRuleSet), cung cấp bảo vệ chống lại các khai thác web phổ biến bao gồm OWASP Top 10. Nhật ký yêu cầu WAF được ghi vào nhóm CloudWatch Logs.

Bạn có thể chỉnh sửa construct rest-api được tạo ra để thêm, xóa hoặc điều chỉnh các quy tắc (ví dụ: để thêm quy tắc dựa trên tốc độ hoặc các nhóm quy tắc được quản lý bổ sung).

Để từ chối (ví dụ: để đính kèm Web ACL của riêng bạn), đặt enableWaf thành false:

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

Ghi nhật ký truy cập

Phần tiêu đề “Ghi nhật ký truy cập”

Đối với REST API, cơ sở hạ tầng được tạo ra sẽ bật ghi nhật ký truy cập theo mặc định, ghi một dòng JSON có cấu trúc cho mỗi yêu cầu vào một nhóm CloudWatch Logs chuyên dụng. Nhóm nhật ký được mã hóa bằng khóa KMS do khách hàng quản lý và được giữ lại trong một năm.

API Gateway ghi nhật ký truy cập bằng cách sử dụng vai trò CloudWatch Logs ở cấp tài khoản. Vai trò này được cấu hình trên cài đặt AWS::ApiGateway::Account, đây là một singleton cho mỗi vùng trên mỗi tài khoản — chỉ có một vai trò duy nhất cho mọi REST API trong vùng. Để quản lý điều này một cách an toàn trên nhiều stack được triển khai độc lập, cơ sở hạ tầng được tạo ra sẽ:

  • Tạo một vai trò CloudWatch Logs được chia sẻ và cấu hình nó trên tài khoản chỉ khi chưa có vai trò hoạt động nào được thiết lập, do đó các triển khai không bao giờ ghi đè vai trò mà một stack khác sở hữu.
  • Giữ nguyên cài đặt tài khoản khi dỡ bỏ, do đó việc hủy một stack không bao giờ vô hiệu hóa ghi nhật ký cho các REST API khác trong vùng.

Vai trò tài khoản được quản lý bởi construct ApiGatewayAccount, một singleton có phạm vi stack được giải quyết thông qua ApiGatewayAccount.ensure(scope). Mỗi stage của REST API phụ thuộc vào nó, và vai trò được cấu hình bởi một tài nguyên tùy chỉnh được hỗ trợ bởi Lambda.

Bạn có thể tùy chỉnh định dạng nhật ký truy cập bằng cách truyền deployOptions khi xây dựng API của bạn:

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

Integrations

Phần tiêu đề “Integrations”

Các construct CDK của REST/HTTP API được cấu hình để cung cấp giao diện type-safe cho việc định nghĩa các tích hợp cho từng operation của bạn.

Các construct CDK cung cấp hỗ trợ tích hợp type-safe đầy đủ như mô tả bên dưới.

Tích hợp mặc định

Phần tiêu đề “Tích hợp mặc định”

Bạn có thể sử dụng defaultIntegrations tĩnh để sử dụng pattern mặc định, định nghĩa một AWS Lambda function riêng biệt cho mỗi operation:

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

Truy cập các tích hợp

Phần tiêu đề “Truy cập các tích hợp”

Bạn có thể truy cập các AWS Lambda function bên dưới thông qua thuộc tính integrations của construct API, theo cách type-safe. Ví dụ, nếu API của bạn định nghĩa một operation tên là sayHello và bạn cần thêm một số quyền cho function này, bạn có thể làm như sau:

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


// sayHello được type theo các operation được định nghĩa trong API của bạn
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({
  effect: Effect.ALLOW,
  actions: [...],
  resources: [...],
}));

Nếu API của bạn sử dụng pattern shared, router Lambda dùng chung được expose dưới dạng api.integrations.$router:

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


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

Tùy chỉnh các tùy chọn mặc định

Phần tiêu đề “Tùy chỉnh các tùy chọn mặc định”

Nếu bạn muốn tùy chỉnh các tùy chọn được sử dụng khi tạo Lambda function cho mỗi tích hợp mặc định, bạn có thể sử dụng phương thức withDefaultOptions. Ví dụ, nếu bạn muốn tất cả các Lambda function của mình nằm trong một Vpc:

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


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

Tùy chỉnh các tùy chọn cho từng operation

Phần tiêu đề “Tùy chỉnh các tùy chọn cho từng operation”

Để tùy chỉnh các tùy chọn được sử dụng để tạo tích hợp mặc định cho các operation cụ thể (mà không ảnh hưởng đến các operation khác), bạn có thể sử dụng phương thức withOperationOptions. Ví dụ, nếu bạn muốn tăng thời gian chờ của Lambda function chỉ cho một operation:

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


// Các operation được chọn vẫn là tích hợp mặc định, vì vậy chúng vẫn được type tương ứng:
api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));

Các tùy chọn bạn chỉ định được hợp nhất với các tùy chọn tích hợp mặc định (và bất kỳ tùy chọn nào được đặt thông qua withDefaultOptions). Lưu ý rằng bạn không thể chỉ định tùy chọn cho các operation mà bạn đã thay thế thông qua withOverrides, vì chúng không còn sử dụng tích hợp mặc định nữa.

Bạn sẽ gặp lỗi type nếu cùng một operation được nhắm mục tiêu bởi cả withOperationOptions và withOverrides, bất kể thứ tự bạn gọi chúng.

Ghi đè các tích hợp

Phần tiêu đề “Ghi đè các tích hợp”

Bạn cũng có thể ghi đè các tích hợp cho các operation cụ thể bằng phương thức withOverrides. Mỗi ghi đè phải chỉ định một thuộc tính integration được type theo construct tích hợp CDK phù hợp cho HTTP hoặc REST API. Phương thức withOverrides cũng là type-safe. Ví dụ, nếu bạn muốn ghi đè một API getDocumentation để trỏ đến tài liệu được lưu trữ bởi một trang web bên ngoài, bạn có thể thực hiện như sau:

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

Bạn cũng sẽ nhận thấy rằng tích hợp được ghi đè không còn có thuộc tính handler khi truy cập nó thông qua api.integrations.getDocumentation.

Bạn có thể thêm các thuộc tính bổ sung vào một tích hợp cũng sẽ được type tương ứng, cho phép các loại tích hợp khác được trừu tượng hóa nhưng vẫn giữ type-safe, ví dụ nếu bạn đã tạo một tích hợp S3 cho REST API và sau này muốn tham chiếu bucket cho một operation cụ thể, bạn có thể làm như sau:

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


// Sau này, có thể trong một file khác, bạn có thể truy cập thuộc tính bucket mà chúng ta đã định nghĩa
// theo cách type-safe
api.integrations.getFile.bucket.grantRead(...);

Ghi đè các Authorizer

Phần tiêu đề “Ghi đè các Authorizer”

Bạn cũng có thể cung cấp options trong tích hợp của mình để ghi đè các tùy chọn method cụ thể như authorizer, ví dụ nếu bạn muốn sử dụng xác thực Cognito cho operation getDocumentation của mình:

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

Tích hợp rõ ràng

Phần tiêu đề “Tích hợp rõ ràng”

Nếu bạn muốn, bạn có thể chọn không sử dụng các tích hợp mặc định và thay vào đó cung cấp trực tiếp một tích hợp cho mỗi operation. Điều này hữu ích nếu, ví dụ, mỗi operation cần sử dụng một loại tích hợp khác nhau hoặc bạn muốn nhận lỗi type khi thêm các operation mới:

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

Integration Pattern

Phần tiêu đề “Integration Pattern”

Các construct CDK API được tạo hỗ trợ hai integration pattern:

  • isolated tạo một Lambda function cho mỗi operation. Đây là mặc định cho các API được tạo.
  • shared tạo một router Lambda mặc định duy nhất và tái sử dụng nó cho mọi operation trừ khi bạn ghi đè các tích hợp cụ thể.

isolated cung cấp cho bạn quyền và cấu hình chi tiết hơn cho mỗi operation. shared giảm sự phân tán của Lambda và tích hợp API Gateway trong khi vẫn cho phép ghi đè có chọn lọc.

Ví dụ, đặt pattern thành 'shared' sẽ tạo một function duy nhất thay vì một function cho mỗi tích hợp:

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


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

Tạo Mã

Phần tiêu đề “Tạo Mã”

Vì operations được định nghĩa trong Smithy, chúng tôi sử dụng tạo mã để cung cấp metadata cho CDK construct để có integrations an toàn kiểu.

Một target generate:<ApiName>-metadata được thêm vào project.json của common constructs để tạo điều kiện cho việc tạo mã này, xuất một file như packages/common/constructs/src/generated/my-api/metadata.gen.ts. Vì điều này được tạo tại thời điểm build, nó bị bỏ qua trong kiểm soát phiên bản.

auth = iam

Cấp Quyền Truy cập (Chỉ IAM)

Phần tiêu đề “Cấp Quyền Truy cập (Chỉ IAM)”

Nếu bạn đã chọn xác thực IAM, bạn có thể sử dụng phương thức grantInvokeAccess để cấp quyền truy cập vào API của bạn:

api.grantInvokeAccess(myIdentityPool.authenticatedRole);

Gọi Smithy API của bạn

Phần tiêu đề “Gọi Smithy API của bạn”

Để gọi API của bạn từ một React website, bạn có thể sử dụng trình tạo connection, cung cấp tạo client an toàn kiểu từ mô hình Smithy của bạn.

Kết nối

Phần tiêu đề “Kết nối”

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

Smithy
React to Smithy APIGọi Smithy API từ một trang web React
SmithyAmazon Aurora
Smithy API to Relational DatabaseKết nối Smithy API với cơ sở dữ liệu quan hệ Aurora
SmithyAmazon DynamoDB
Smithy API to TypeScript DynamoDBKết nối Smithy API với bảng DynamoDB