AWS 云控制 API，一个访问 AWS & 第三方服务的统一 API

今天，我很高兴地宣布推出 AWS 云控制 API 是一组通用的应用程序编程接口 (API)，设计旨在让开发人员轻松管理其 AWS 和第三方服务。

AWS 提供了最广泛、最深入的云服务组合。构建者利用这些服务来构建任何类型的云基础设施。它从 15 年前始于 Amazon Simple Storage Service (Amazon S3) 并发展了 200 多项服务。每项 AWS 服务都有一个特定的 API，其中包含自己的词汇表、输入参数和错误报告。例如，您可以使用 S3 CreateBucket API 创建 Amazon Simple Storage Service (Amazon S3) 存储桶，并使用 Amazon Elastic Compute Cloud (Amazon EC2) RunInstances API 创建 EC2 实例。

有些人使用 AWS API 构建基础设施即代码，有些人用它们检查并自动改善安全状况，另一些人则将它们用于配置管理或预置和配置高性能计算集群。使用案例数不胜数。

随着应用程序和基础设施变得越来越复杂，您可以跨越更多的 AWS 服务工作，学习和管理不同的 API 就变得越来越困难。如果您还在基础设施中使用第三方服务，这一挑战就会加剧，因为您必须构建和维护自定义代码才能同时管理 AWS 和第三方服务。

云控制 API 是一组标准的 API，可跨数百项 AWS 服务（正在添加更多服务）和数十项第三方服务（在不断增长）创建、读取、更新、删除和列出 (CRUDL) 资源。

它公开了五个常用的动词（CreateResource、GetResource、UpdateResource、DeleteResource、ListResource）来管理服务的生命周期。例如，要创建 Amazon Elastic Container Service (Amazon ECS) 集群或 AWS Lambda 函数，您可以调用同一个 CreateResource API，将要创建的资源的类型和属性作为参数传递：Amazon ECS 集群或 Lambda 函数。输入参数由使用 JSON 的统一资源模型定义。同样，返回类型和错误消息在所有动词和所有资源中都是统一的。

云控制 API 现在为数百种 AWS 资源提供支持，我们将在未来几个月里继续跨 Amazon Elastic Compute Cloud (Amazon EC2) 和 Amazon Simple Storage Service (Amazon S3) 等服务增加对现有 AWS 资源的支持。它通常会在发布当天支持新的 AWS 资源。

直到今天，当我想获取有关 Lambda函数或 Amazon Kinesis 流的详细信息时，我使用 get-function API 调用 Lambda，并使用 describe-stream API 调用 Kinesis。请注意，在下面的示例中，这两个 API 调用的不同之处：它们具有不同的名称、不同的命名约定、不同的 JSON 输出等。

aws lambda get-function --function-name TictactoeDatabaseCdkStack
{
    "Configuration": {
        "FunctionName": "TictactoeDatabaseCdkStack",
        "FunctionArn": "arn:aws:lambda:us-west-2:0123456789:function:TictactoeDatabaseCdkStack",
        "Runtime": "nodejs14.x",
        "Role": "arn:aws:iam::0123456789:role/TictactoeDatabaseCdkStack",
        "Handler": "framework.onEvent",
        "CodeSize": 21539,
        "Timeout": 900,
        "MemorySize": 128,
        "LastModified": "2021-06-07T11:26:39.767+0000",

...

aws kinesis describe-stream --stream-name AWSNewsBlog
{
    "StreamDescription": {
        "Shards": [
            {
                "ShardId": "shardId-000000000000",
                "HashKeyRange": {
                    "StartingHashKey": "0",
                    "EndingHashKey": "340282366920938463463374607431768211455"
                },
                "SequenceNumberRange": {
                    "StartingSequenceNumber": "49622132796672989268327879810972713309953024040638611458"
                }
            }
        ],
        "StreamARN": "arn:aws:kinesis:us-west-2:012345678901:stream/AWSNewsBlog",
        "StreamName": "AWSNewsBlog",
        "StreamStatus": "ACTIVE",
        "RetentionPeriodHours": 24,
        "EncryptionType": "NONE",
        "KeyId": null,
        "StreamCreationTimestamp": "2021-09-17T14:58:20+02:00"
    }
}

相比之下，当使用云控制 API 时，我使用单个 API 名称 get-resource 并收到一致的输出。

aws cloudcontrol get-resource        \
    --type-name AWS::Kinesis::Stream \
    --identifier NewsBlogDemo
{
   "TypeName": "AWS::Kinesis::Stream",
   "ResourceDescription": {
      "Identifier": "NewsBlogDemo",
      "Properties": "{\"Arn\":\"arn:aws:kinesis:us-west-2:486652066693:stream/NewsBlogDemo\",\"RetentionPeriodHours\":168,\"Name\":\"NewsBlogDemo\",\"ShardCount\":3}"
   }
}

同样，为了创建上面的资源，我使用了 create-resource API。


aws cloudcontrol create-resource    \
   --type-name AWS::Kinesis::Stream \
   --desired-state "{"Name": "NewsBlogDemo","RetentionPeriodHours":168, "ShardCount":3}"

我认为，有三种类型的构建者将采用云控制 API：

构建者
第一个社区是使用 AWS 服务 API 管理其基础设施或其客户的基础设施的构建者。那些需要使用低级别 AWS 服务 API 而不是更高级别工具的构建者。例如，我知道代表其客户管理 AWS 基础设施的公司。许多开发的解决方案列出和描述在客户的 AWS 账户中部署的所有资源，以便进行管理和计费。他们通常会构建特定的工具来满足自己的需求，但发现很难跟上新的 AWS 服务和功能。云控制 API 通过提供一致的、以资源为中心的方法简化这种类型的工具。它可以更轻松地跟上新的 AWS 服务和功能。

另一个例子：Stedi 是一个以开发人员为中心的平台，用于构建与任何业务系统集成的自动化电子数据交换 (EDI) 解决方案。“我们非常关注 Stedi 的基础设施即代码 (IaC)，并且一直在寻找一种程序化的方法来发现和删除不再通过 CloudFormation 管理的旧式云资源，从而帮助我们降低复杂性并管理成本”，Stedi, Inc. 的无服务器工程师 Olaf Conjin 说。“借助 AWS 云控制 API”，我们的团队可以轻松列出所有这些旧资源，将它们与 CloudFormation 托管资源进行交叉引用，应用其他逻辑并删除旧资源。通过使用云控制 API 删除这些未使用的旧资源，我们可以更简单、更快捷地管理我们的云支出。借助云控制 API，我们无需编写和维护自定义代码即可发现和删除每种类型的资源，从而帮助我们提高开发人员的速度。”

APN 合作伙伴
第二个受益于云控制 API 的社区是 APN 合作伙伴，例如 HashiCorp（Terraform 的制造商）和 Pulumi，以及提供依赖于 AWS 服务 API 的其他 APN 合作伙伴。当 AWS 发布新服务或功能时，我们合作伙伴的工程团队需要学习、集成和测试一组新的 AWS 服务 API，以便在其产品中公开这些 API。这是一个耗时的过程，通常会导致 AWS 版本与其解决方案中的服务或功能可用性之间存在滞后。借助新的云控制 API，合作伙伴现在可以使用统一的 API 动词、通用输入参数和常见错误类型构建独特的 REST API 代码库。他们只需要合并标准化的预定义统一资源模型即可与作为 REST 资源公开的新 AWS 服务进行交互。

启动合作伙伴
HashiCorp 和 Pulumi 是我们的启动合作伙伴，今天，这两个解决方案都与云控制 API 进行了集成。

HashiCorp 提供云基础设施自动化软件，使组织能够为任何应用程序预置、保护、连接和运行任何基础设施。“AWS 云控制 API 使我们的团队能够更轻松地构建解决方案，以与新的和现有的 AWS 服务集成”，HashiCorp 产品执行副总裁 James Bayer 表示。“将 HashiCorp Terraform 与 AWS 云控制 API 集成意味着开发人员能够使用新发布的 AWS 功能和服务，通常在发布当天即可使用。”

Pulumi 是新的 AWS 原生提供商，由 AWS 云控制 API 提供支持，“让 Pulumi 的用户能够更快地访问最新的 AWS 创建，通常在其发布当天即可访问，无需我们手动实施支持”，Pulumi 首席执行官 Joe Duffy 表示。“AWS 云控制 API 提供的 AWS 资源的完整表面积现在可以通过 Python、TypeScript、.NET 和 Go 等熟悉的语言、使用标准 IDE、程序包管理器和测试框架高保真度、高质量地进行自动化。使用这个新的提供商，开发人员和基础设施团队可以比以往更快、更有信心地开发和交付现代 AWS 应用程序和基础设施。”

要了解有关 HashiCorp 和 Pulumi 与云控制 API 集成的更多信息，请参阅他们的博客文章和公告。一旦链接可用，我会在此添加它们。

AWS 客户
将受益于云控制 API 的第三种构建者是使用 Terraform 或 Pulumi 之类的解决方案的 AWS 客户。您也可以从云控制 API 中受益。例如，使用新的 Terraform AWS 云控制提供商或 Pulumi 的 AWS 原生提供商时，您通常可以在发布当天获得新的 AWS 服务和功能。

现在您已经了解了这些益处，我们来看看云控制 API 的实际应用。

工作原理
要开始使用云控制 API，首先确保我使用的是最新的 AWS 命令行界面 (CLI) 版本。根据 CLI 的安装方式，可以通过不同的方法来更新 CLI。云控制 API 也可以通过我们的 AWS 开发工具包提供。

为了创建 AWS Lambda 函数，首先创建一个 index.py 处理程序、压缩该程序，然后将压缩文件上传到我的私有存储桶之一。我注意到 S3 存储桶位于我将在其中创建 Lambda 函数的同一 AWS 区域中：

cat << EOF > index.py  
heredoc> import json 
def lambda_handler(event, context):
    return {
        'statusCode': 200,
        'body': json.dumps('Hello from Lambda!')
    }
EOF

zip index.zip index.py
aws s3 cp index.zip s3://private-bucket-seb/index.zip

然后，我调用 create-resource API，传递相应 CloudFormation 资源所需的同一组参数。在此示例中，根据 CloudFormation AWS::Lambda::Function 文档，Code, Role、Runtime 和 Handler 参数是必需的。

aws cloudcontrol create-resource          \
       --type-name AWS::Lambda::Function   \
       --desired-state '{"Code":{"S3Bucket":"private-bucket-seb","S3Key":"index.zip"},"Role":"arn:aws:iam::0123456789:role/lambda_basic_execution","Runtime":"python3.9","Handler":"index.lambda_handler"}' \
       --client-token 123


{
    "ProgressEvent": {
        "TypeName": "AWS::Lambda::Function",
        "RequestToken": "56a0782b-2b26-491c-b082-18f63d571bbd",
        "Operation": "CREATE",
        "OperationStatus": "IN_PROGRESS",
        "EventTime": "2021-09-26T12:05:42.210000+02:00"
    }
}

我可能会再次调用相同的命令来获取状态或了解最终的错误：

aws cloudcontrol create-resource          \
       --type-name AWS::Lambda::Function   \
       --desired-state '{"Code":{"S3Bucket":"private-bucket-seb","S3Key":"index.zip"},"Role":"arn:aws:iam::0123456789:role/lambda_basic_execution","Runtime":"python3.9","Handler":"index.lambda_handler"}' \
       --client-token 123

{
    "ProgressEvent": {
        "TypeName": "AWS::Lambda::Function",
        "Identifier": "ukjfq7sqG15LvfC30hwbRAMfR-96K3UNUCxNd9",
        "RequestToken": "f634b21d-22ed-41bb-9612-8740297d20a3",
        "Operation": "CREATE",
        "OperationStatus": "SUCCESS",
        "EventTime": "2021-09-26T19:46:46.643000+02:00"
    }
}

在这里，OperationStatus 是 SUCCESS，函数名称为 ukjfq7sqG15LvfC30hwbRAMfR-96K3UNUCxNd9（如果我想要某个内容更具有描述性，我可以传递自己的姓名 :-)）

然后我调用 Lambda 函数来确保它按预期工作：

aws lambda invoke \
    --function-name ukjfq7sqG15LvfC30hwbRAMfR-96K3UNUCxNd9 \
    out.txt && cat out.txt && rm out.txt 

{
    "StatusCode": 200,
    "ExecutedVersion": "$LATEST"
}
{"statusCode": 200, "body": "\"Hello from Lambda!\""}

完成后，我会使用云控制 API 删除 Lambda 函数：

aws cloudcontrol delete-resource \
     --type-name AWS::Lambda::Function \
     --identifier ukjfq7sqG15LvfC30hwbRAMfR-96K3UNUCxNd9 
{
    "ProgressEvent": {
        "TypeName": "AWS::Lambda::Function",
        "Identifier": "ukjfq7sqG15LvfC30hwbRAMfR-96K3UNUCxNd9",
        "RequestToken": "8923991d-72b3-4981-8160-4d9a585965a3",
        "Operation": "DELETE",
        "OperationStatus": "IN_PROGRESS",
        "EventTime": "2021-09-26T20:06:22.013000+02:00"
    }
}

幂等性
您可能已经注意到传递到 create-resource API 调用的 client-token 参数。Create、Update 和 Delete 请求全部都接受 ClientToken，该令牌被用于确保请求的幂等性。

我们建议始终传递客户端令牌。如果需要重试，这将消除请求的歧义。否则，您可能会遇到意外的错误，例如 ConcurrentOperationException 或 AlreadyExists。
我们建议客户端令牌对于每个请求始终是唯一的，例如通过传递 UUID。

还有一件事
AWS 云控制 API 数据源的核心有一个 CloudFormation 公有注册表，它由我的同事 Steve 本月早些时候在本博客文章中发布。通过它，任何人都可以通过 CloudFormation 和 AWS CDK 公开一组 AWS 资源。这是 AWS 服务团队现在用来将其服务和功能作为 CloudFormation 和 AWS CDK 资源发布的机制。多家第三方供应商也在 CloudFormation 公有注册表中发布了其解决方案。所有已发布的资源都使用以统一的方式定义资源、其性能及其属性的标准架构进行建模。

AWS 云控制 API 是在 CloudFormation 公有注册表中发布的资源之上的 CRUDL API 层。注册表中发布的任何资源都会使用标准 JSON 模式公开其属性。然后，可以使用云控制 API 创建、更新、删除或列出资源，而无需进行额外工作。

例如，假设我决定公开一个公有 CloudFormation 堆栈来让 AWS 客户基于 EC2 实例创建 VPN 服务器。我为 VPNServer 资源类型建模并将其发布到 CloudFormation 公有注册表中。由于我没有额外的工作，我的自定义资源“VPNServer”现在可以通过云控制 API REST API 向所有 AWS 客户提供。不仅如此，它还可以通过 Hashicorp 的 Terraform 和 Pulumi 等解决方案，以及未来可能采用云控制 API 的其他解决方案自动提供。

值得一提的是，云控制 API 并非旨在取代传统的 AWS 服务级别 API。它们仍然存在并将永远存在，但是我们认为云控制 API 使用起来更简单，更一致，您应该将其用于新应用程序。

可用性和定价
云控制 API 已在中国之外的所有 AWS 区域推出。

您只需为基础 AWS 资源（例如 CloudWatch 日志或 Lambda 函数调用）的使用量付费，或者为与使用第三方资源（例如 Datadog 监视器或 MongoDB Atlas 集群）相关联的处理程序操作次数和处理程序操作持续时间付费。没有最低费用，也无需预先承诺。

我迫不及待地想知道您将在这个新的云控制 API 的基础上构建什么。立即构建！

– seb

亚马逊AWS官方博客

AWS 云控制 API，一个访问 AWS & 第三方服务的统一 API