Skip to main contentCertyo Developer Portal

Amazon Web Services 集成

使用 EventBridge、Lambda、Step Functions 和 API Gateway 将 Certyo 与 AWS 集成的参考架构。

EventBridge API Destinations
EventBridge API Destinations 支持带指数退避的自动重试 — 配置最大 185 次重试以实现 24 小时覆盖。

前提条件

  • 具有 EventBridge、Lambda、Step Functions 和 Secrets Manager IAM 权限的 AWS 账户
  • AWS CLI v2 已配置凭据
  • Certyo API 密钥（存储在 AWS Secrets Manager 中 — 参见下面的 身份验证 部分）
  • Node.js 20+ 或 Python 3.12+（用于 Lambda 开发）

参考架构

此架构利用 AWS 原生事件路由和无服务器计算与 Certyo 集成：

AWS Reference Architecture
Source System ──► EventBridge ──► API Destination (Certyo) ──► POST /api/v1/records
                          │                                           │
                     DLQ (SQS)                                  Step Functions
                   for failed                               (verification workflow)
                    deliveries                                        │
                                                              ┌──────┴──────┐
                                                              │  Wait 90s   │
                                                              │  Verify     │
                                                              │  Branch     │
                                                              └──────┬──────┘
                                                                     │
                                                              SNS notification
                                                           (anchored / failed)

EventBridge 从您的源系统（S3、DynamoDB Streams、自定义应用）接收领域事件。对于简单转发，API Destinations 直接调用 Certyo 无需 Lambda 中间层。对于复杂转换，Lambda 在采集前处理事件。Step Functions 编排多步骤验证工作流。

EventBridge API Destinations

最简单的集成模式：EventBridge 通过 API Destination 直接调用 Certyo API。无需 Lambda 代码即可实现简单事件转发。

工作原理

  • 连接 — 使用 API_KEY 身份验证类型存储 Certyo API 密钥。如果您更新密钥，EventBridge 会管理凭据轮换。
  • API Destination — 定义 Certyo endpoint URL、HTTP 方法和调用速率限制。
  • 规则 — 按来源、详情类型或自定义模式匹配传入事件，并将其路由到 API Destination。
  • Input Transformer — 将您的事件 schema 映射到 Certyo 记录 payload — 无需任何 Lambda 代码。
  • 重试 + DLQ — 内置重试带指数退避（最多 24 小时 185 次重试）。失败的事件落入 SQS dead-letter 队列。

Lambda Functions

对于需要在采集前进行转换、丰富或条件逻辑的事件，使用 Lambda 作为处理层：

  • S3 触发器 — bucket 中的新对象触发 Lambda，读取文件、提取记录并将每条发送到 Certyo
  • DynamoDB Streams — 从 DynamoDB 表捕获更改数据并将修改的项目作为 Certyo 记录转发
  • Webhook 处理程序 — 通过 API Gateway 接收第三方系统的 webhook，转换并采集

Step Functions

编排多步骤工作流：采集记录、等待锚定、验证结果，并根据成功或失败进行分支：

  • Standard Workflow — 适用于长期运行的验证流（最长 1 年执行）。使用 Wait 状态暂停等待 Certyo 约 60-90 秒的锚定窗口。
  • Express Workflow — 适用于高容量、短时间执行（最长 5 分钟）。适合批量采集，验证单独处理。

API Gateway

为内部消费者使用 API Gateway 前置 Certyo，用于使用计划、节流和 API 密钥管理：

  • 创建 REST API 代理将请求转发到 https://www.certyos.com/api/v1/
  • 添加带节流的使用计划（如每个消费者 100 请求/秒）和月度配额
  • 通过 Lambda authorizer 或 VTL 映射模板注入 Certyo X-API-Key
  • 内部消费者使用自己的 API Gateway 密钥进行身份验证 — 他们永远看不到 Certyo 密钥

代码示例

certyo_s3_ingest.pypython
import json
import os
import urllib.parse
import boto3
import urllib3

secrets_client = boto3.client("secretsmanager")
s3_client = boto3.client("s3")
http = urllib3.PoolManager()

CERTYO_API_URL = os.environ.get("CERTYO_API_URL", "https://www.certyos.com")
CERTYO_TENANT_ID = os.environ["CERTYO_TENANT_ID"]
SECRET_ARN = os.environ["CERTYO_SECRET_ARN"]

_api_key_cache = None


def get_api_key():
    global _api_key_cache
    if _api_key_cache is None:
        secret = secrets_client.get_secret_value(SecretId=SECRET_ARN)
        _api_key_cache = json.loads(secret["SecretString"])["apiKey"]
    return _api_key_cache


def handler(event, context):
    """
    Triggered by S3 PutObject events. Reads the uploaded JSON file,
    extracts records, and sends each to Certyo for blockchain anchoring.
    """
    api_key = get_api_key()
    results = []

    for record in event["Records"]:
        bucket = record["s3"]["bucket"]["name"]
        key = urllib.parse.unquote_plus(record["s3"]["object"]["key"])

        print(f"Processing s3://{bucket}/{key}")

        # Read the S3 object
        obj = s3_client.get_object(Bucket=bucket, Key=key)
        body = json.loads(obj["Body"].read().decode("utf-8"))

        # Support single record or array of records
        items = body if isinstance(body, list) else [body]

        for item in items:
            record_id = item.get("id", key.split("/")[-1].replace(".json", ""))

            payload = {
                "tenantId": CERTYO_TENANT_ID,
                "database": f"s3-{bucket}",
                "collection": key.rsplit("/", 1)[0] if "/" in key else "root",
                "recordId": record_id,
                "recordVersion": str(item.get("version", "1")),
                "operationType": "upsert",
                "recordPayload": item,
                "sourceTimestamp": record["eventTime"],
                "idempotencyKey": f"{record_id}-{record['eventTime'][:10]}",
            }

            response = http.request(
                "POST",
                f"{CERTYO_API_URL}/api/v1/records",
                body=json.dumps(payload),
                headers={
                    "X-API-Key": api_key,
                    "Content-Type": "application/json",
                },
            )

            result = json.loads(response.data.decode("utf-8"))

            if response.status != 202:
                print(f"ERROR: Certyo returned {response.status} for {record_id}: {result}")
                raise Exception(f"Ingestion failed for {record_id}: {response.status}")

            print(f"Record {record_id} accepted. Hash: {result['recordHash']}")
            results.append(result)

    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": f"Ingested {len(results)} records",
            "records": results,
        }),
    }

身份验证

推荐的身份验证模式使用 AWS 原生密钥管理配合 IAM 进行服务间授权：

  • Secrets Manager — 将 Certyo X-API-Key 存储为密钥。如果您的组织需要，启用自动轮换。
  • EventBridge 连接 — 连接对象安全存储 API 密钥并将其注入每个 API Destination 请求。您无需在应用代码中处理密钥。
  • Lambda 执行角色 — 授予 Lambda 函数对特定密钥 ARN 的 secretsmanager:GetSecretValue 。使用最小权限原则。
  • API Gateway API 密钥 — 对于内部消费者，发放绑定到使用计划的 API Gateway 密钥。网关通过 Lambda authorizer 或映射模板注入 Certyo 密钥。
IAM policy for Lambda to read Certyo secretjson
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadCertyoApiKey",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:certyo/api-key-*"
    }
  ]
}

成本优化

根据您的工作负载选择正确的集成模式以最小化 AWS 成本：

  • EventBridge API Destinations（最经济） — 无 Lambda 调用成本。您只需为 EventBridge 事件（每百万事件 $1.00）和 API Destination 调用付费。用于不需要转换的简单事件转发。
  • EventBridge + Input Transformer — 如果只需要重塑事件 payload（重命名字段、提取嵌套值），使用 EventBridge Input Transformer 而非 Lambda。零计算成本。
  • Lambda（用于转换） — 仅在需要从 S3 读取、调用外部 API 或在采集前应用复杂业务逻辑时使用 Lambda。使用 ARM64 (Graviton) 可节省 20% 成本。
  • Step Functions Express — 对于高容量验证工作流（>100K 执行/月），Express Workflows 比 Standard Workflows 最多便宜 80%。
提示
对于大多数集成，EventBridge API Destinations 配合 Input Transformer 无需编写一行 Lambda 代码即可处理所有事务。从这里开始，仅在需要时添加 Lambda。

后续步骤

  • 部署上面的 CDK 堆栈，在几分钟内配置完整的 EventBridge 管道
  • 发布测试事件到 domain-events 总线并验证它到达 Certyo
  • 部署 Step Functions 验证工作流实现端到端锚定确认
  • 查看 采集指南 了解记录 schema 和幂等性详情
  • 参见 验证指南 了解密码学证明详情
AI Integration · v1.0.0

AI Integration Skill

Download a skill file that enables AI agents to generate working AWS + Certyo integration code for any language or framework.

v1.0.0
What is this?
A markdown file containing AWS-specific field mappings, authentication setup, code examples, and integration patterns for Certyo. Drop it into your AI agent's context and ask it to generate integration code.

What's inside

  • 身份验证 — EventBridge 连接配合 API Key，Lambda 配合 Secrets Manager
  • 架构 — EventBridge → API Destination 或 Lambda → Certyo → Step Functions 验证
  • 代码示例 — Python Lambda、CDK TypeScript 堆栈、Step Functions ASL 工作流
  • API Destinations — 零 Lambda 直接转发到 Certyo 配合重试策略
  • Step Functions — 带有 Wait 状态、重试循环和分支的验证工作流
  • 成本优化 — API Destinations vs Lambda vs Express Workflows 对比

How to use

Claude Code

Place the file in your project's .claude/commands/ directory, then use it as a slash command:

# Download the skill file
mkdir -p .claude/commands
curl -o .claude/commands/certyo-aws.md \
  https://www.certyos.com/developers/skills/certyo-aws-skill.md

# Use it in Claude Code
/certyo-aws "生成一个将事件转发到 Certyo 的 EventBridge API Destination"

Cursor / Copilot / Any AI Agent

Add the file to your project root or attach it to a conversation. The AI agent will use the AWS-specific patterns, field mappings, and code examples to generate correct integration code.

# Add to your project
curl -o CERTYO_AWS.md \
  https://www.certyos.com/developers/skills/certyo-aws-skill.md

# Then in your AI agent:
"Using the Certyo AWS spec in CERTYO_AWS.md,
 生成一个将事件转发到 certyo 的 eventbridge api destination"

CLAUDE.md Context File

Append the skill file to your project's CLAUDE.md so every Claude conversation has AWS + Certyo context automatically.

# Append to your project's CLAUDE.md
echo "" >> CLAUDE.md
echo "## Certyo AWS Integration" >> CLAUDE.md
cat CERTYO_AWS.md >> CLAUDE.md