架构注册表入门 - AWS Glue
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

架构注册表入门

以下各节概述和演示了如何设置和使用架构注册表。有关架构注册表概念和组件的信息,请参阅AWS Glue 架构注册表

安装 SerDe 库

注意

先决条件:在完成以下步骤之前,您需要运行 Apache Kafka (MSK) 或 Apache Kafka 集群的托管流式处理。您的创建者和使用者需要在 Java 8 或更高版本上运行。

SerDe 库提供了用于序列化和反序列化数据的框架。

您将为生成数据的应用程序安装开源串行器(统称为“串行器”)。序列化程序处理序列化、压缩以及与架构注册表的交互。序列化器自动从写入到与架构注册表兼容的目标(如 Amazon MSK)的记录中提取架构。同样,您将在使用数据的应用程序上安装开源解串器。

在创建者和使用者上安装库:

  1. 在创建者和使用者的 pom.xml 文件中,通过下面的代码添加此依赖项:

    <dependency> <groupId>software.amazon.glue</groupId> <artifactId>schema-registry-serde</artifactId> <version>1.0.0</version> </dependency>

    或者,您可以克隆 AWS Glue 架构注册表 Github 存储库

  2. 使用以下必需属性设置您的创建器:

    props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName()); // Can replace StringSerializer.class.getName()) with any other key serializer that you may use props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, AWSKafkaAvroSerializer.class.getName()); props.put(AWSSchemaRegistryConstants.AWS_REGION, "us-east-2");

    如果没有现有架构,则需要打开自动注册 (下一步)。如果您确实有一个要应用的架构,请将“my-schema”替换为您的架构名称。如果架构自动注册已关闭,还必须提供“registry-name”。如果架构是在“default-registry”下创建的,则可以省略注册表名称。

  3. (可选)设置任意这些可选的创建者属性。有关详细的属性描述,请参阅 ReadMe 文件

    props.put(AWSSchemaRegistryConstants.SCHEMA_AUTO_REGISTRATION_SETTING, "true"); // If not passed, uses "false" props.put(AWSSchemaRegistryConstants.SCHEMA_NAME, "my-schema"); // If not passed, uses transport name (topic name in case of Kafka, or stream name in case of Kinesis Data Streams) props.put(AWSSchemaRegistryConstants.REGISTRY_NAME, "my-registry"); // If not passed, uses "default-registry" props.put(AWSSchemaRegistryConstants.CACHE_TIME_TO_LIVE_MILLIS, "86400000"); // If not passed, uses 86400000 (24 Hours) props.put(AWSSchemaRegistryConstants.CACHE_SIZE, "10"); // default value is 200 props.put(AWSSchemaRegistryConstants.COMPATIBILITY_SETTING, Compatibility.FULL); // Pass a compatibility mode. If not passed, uses Compatibility.BACKWARD props.put(AWSSchemaRegistryConstants.DESCRIPTION, "This registry is used for several purposes."); // If not passed, constructs a description props.put(AWSSchemaRegistryConstants.COMPRESSION_TYPE, AWSSchemaRegistryConstants.COMPRESSION.ZLIB); // If not passed, records are sent uncompressed

    自动注册将在默认注册表(“default-registry”)下注册架构版本。如果在上一步中未指定 SCHEMA_NAME,则主题名称将推断为 SCHEMA_NAME

    有关兼容性模式的更多信息,请参阅架构版本控制和兼容性

  4. 使用以下必需属性设置您的使用者:

    props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName()); props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, AWSKafkaAvroDeserializer.class.getName()); props.put(AWSSchemaRegistryConstants.AWS_REGION, "us-east-2"); // Pass an AWS Region props.put(AWSSchemaRegistryConstants.AVRO_RECORD_TYPE, AvroRecordType.GENERIC_RECORD.getName());
  5. (可选)设置这些可选的使用者属性。有关详细的属性描述,请参阅 ReadMe 文件

    properties.put(AWSSchemaRegistryConstants.CACHE_TIME_TO_LIVE_MILLIS, "86400000"); // If not passed, uses 86400000 props.put(AWSSchemaRegistryConstants.CACHE_SIZE, "10"); // default value is 200 props.put(AWSSchemaRegistryConstants.SECONDARY_DESERIALIZER, "com.amazonaws.services.schemaregistry.deserializers.external.ThirdPartyDeserializer"); // For migration fall back scenario

将 AWS CLI 用于 AWS Glue 架构注册表 API

要对 AWS Glue 架构注册表 API 使用 AWS CLI,请确保将您的 AWS CLI 更新为最新版本。

创建注册表

您可以使用默认注册表,也可以使用 AWS Glue API 或 AWS Glue 控制台根据需要创建任意数量的新注册表。

AWS Glue API

您可以使用这些步骤通过 AWS Glue API 执行此任务。

要添加新注册表,请使用 CreateRegistry 操作 API。指定 RegistryName 作为要创建的注册表的名称,最大长度为 255,仅包含字母、数字、连字符、下划线、美元符号或哈希标记。

Description 指定为不超过 2048 个字节的字符串,与 URI 地址多行字符串模式匹配。

(可选) 为注册表指定一个或多个 Tags,作为键值对的映射数组。

aws glue create-registry --registry-name registryName1 --description description

创建注册表时,系统会为您的注册表分配一个 Amazon 资源名称 (ARN),您可以在 API 响应的 RegistryArn 中查看该名称。现在,您已经创建了一个注册表,接下来为该注册表创建一个或多个架构。

AWS Glue 控制台

要在 AWS Glue 控制台中添加新注册表,请执行以下操作:

  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schema registries (架构注册表)

  3. 选择 Add registry (添加注册表)

  4. 输入注册表的注册表名称,包括字母、数字、连字符或下划线。此名称不能更改。

  5. 输入注册表的 Description (描述)(可选)。

  6. (可选)将一个或多个标签应用于注册表。选择 Add new tag (添加新标签) 并指定 Tag key (标签键) 和(可选)Tag value (标签值)

  7. 选择 Add registry (添加注册表)


			创建注册表的示例。

创建注册表时,系统会为其分配一个 Amazon 资源名称 (ARN),您可以从 Schema registries (架构注册表) 中的列表中选择注册表来查看该名称。现在,您已经创建了一个注册表,接下来为该注册表创建一个或多个架构。

创建架构

您可以使用 AWS Glue API 或 AWS Glue 控制台创建架构。

AWS Glue API

您可以使用这些步骤通过 AWS Glue API 执行此任务。

要添加新架构,请使用 CreateSchema 操作 API。

指定 RegistryId 结构以指示架构的注册表。或者,忽略 RegistryId 以使用默认注册表。

将包含字母、数字、连字符或下划线的 SchemaName 指定为 DataFormatAVRO

指定 Compatibility 模式:

  • 向后 (推荐) — 使用者可以读取当前版本和早期版本。

  • Backward all - 使用者可以读取当前版本和所有先前版本。

  • 转发 - 使用者可以读取当前版本和后续版本。

  • Forward all - 使用者可以读取当前版本和所有后续版本。

  • 完整 – 向后和向前组合。

  • Full all - 全部向后和全部转发的组合。

  • – 不执行兼容性检查。

  • Disabled – 阻止此架构的任何版本控制。

(可选) 为架构指定 Tags

指定 SchemaDefinition 以 Avro 数据格式定义架构。请参阅示例。

aws glue create-schema --registry-id RegistryName="registryName1" --schema-name testschema --compatibility NONE --data-format AVRO --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}"
aws glue create-schema --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1" --schema-name testschema --compatibility NONE --data-format AVRO --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}"

AWS Glue 控制台

要使用 AWS Glue 控制台添加新架构,请执行以下操作:

  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schemas (架构)

  3. 选择 Add schema (添加架构)

  4. 输入 Schema name (架构名称),其中包括字母、数字、连字符、下划线、美元符号或哈希标记。此名称不能更改。

  5. 选择将从下拉菜单中选择架构所在的 Registry (注册表)。父注册表在创建后无法更改。

  6. Data format (数据格式) 保留为 Apache Avro。此格式适用于此架构的所有版本。

  7. 选择 Compatibility mode (兼容性模式)

    • 向后(推荐) — 接收方可以读取当前版本和早期版本。

    • 全部向后 — 接收方可以读取当前版本和所有先前版本。

    • 转发 - 发件人可以写入当前版本和早期版本。

    • 全部转发 - 发件人可以写入当前和所有先前的版本。

    • 完整 – 向后和向前组合。

    • Full All - 全部向后和全部转发的组合。

    • - 不执行兼容性检查。

    • Disabled – 阻止此架构的任何版本控制。

  8. 为最多包含 250 个字符的注册表输入可选的 Description (描述)

    
			创建架构的示例。
  9. (可选)将一个或多个标签应用于架构。选择 Add new tag (添加新标签) 并指定 Tag key (标签键) 和(可选)Tag value (标签值)

  10. First schema version (第一个架构版本) 框中,输入或粘贴初始 Apache Avro 架构。请参阅使用 Avro 数据格式.

  11. (可选)选择 Add metadata (添加元数据) 以添加版本元数据来注释或对架构版本进行分类。

  12. 选择 Create schema and version (创建架构和版本)


			创建架构的示例。

将创建架构并显示在 Schemas (架构) 下的列表中。

使用 Avro 数据格式

Avro 提供数据序列化和数据交换服务。Avro 以 JSON 格式存储数据定义,便于阅读和解释。数据本身以二进制格式存储。

有关定义 Apache Avro 架构的信息,请参阅 Apache Avro 规范

更新架构或注册表

创建后,您可以编辑架构、架构版本或注册表。

更新注册表

您可以使用 AWS Glue API 或 AWS Glue 控制台更新注册表。无法编辑现有注册表的名称。您可以编辑注册表的描述 。

AWS Glue API

要更新现有注册表,请使用 UpdateRegistry 操作 API。

指定 RegistryId 结构以指示要更新的注册表。传递 Description 以更改注册表的描述。

aws glue update-registry --description updatedDescription --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1"

AWS Glue 控制台

使用 AWS Glue 控制台更新注册表:

  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schema registries (架构注册表)

  3. 通过选中注册表列表的复选框,从注册表列表中选择注册表。

  4. Action (操作) 菜单中,选择 Edit registry (编辑注册表)

更新架构

您可以更新架构的描述或兼容性设置。

要更新现有架构,请使用 UpdateSchema 操作 API。

指定 SchemaId 结构以指示要更新的架构。必须提供 VersionNumberCompatibility 之一。

代码示例 11:

aws glue update-schema --description testDescription --schema-id SchemaName="testSchema1",RegistryName="registryName1" --schema-version-number LatestVersion=true --compatibility NONE
aws glue update-schema --description testDescription --schema-id SchemaArn="arn:aws:glue:us-east-2:901234567890:schema/registryName1/testSchema1" --schema-version-number LatestVersion=true --compatibility NONE

添加架构版本

添加架构版本时,您需要比较版本以确保新架构将被接受。

要将新版本添加到现有架构,请使用 RegisterSchemaVersion 操作 API。

指定 SchemaId 结构以指示要为其添加版本的架构,并指定 SchemaDefinition 以 Avro 数据格式定义架构。

代码示例 12:

aws glue register-schema-version --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}" --schema-id SchemaArn="arn:aws:glue:us-east-1:901234567890:schema/registryName/testschema"
aws glue register-schema-version --schema-definition "{\"type\": \"record\", \"name\": \"r1\", \"fields\": [ {\"name\": \"f1\", \"type\": \"int\"}, {\"name\": \"f2\", \"type\": \"string\"} ]}" --schema-id SchemaName="testschema",RegistryName="testregistry"
  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schemas (架构)

  3. 通过选中其框,从架构列表中选择架构。

  4. 通过选中复选框,从列表中选择一个或多个架构。

  5. Action (操作) 菜单中,选择 Register new version (注册新版本)

  6. New version 框中,输入或粘贴您的新 Apache Avro 架构。

  7. 选择 Compare with previous version (与上一个版本进行比较) 以查看与上一个架构版本的区别。

  8. (可选)选择 Add metadata (添加元数据) 以添加版本元数据来注释或对架构版本进行分类。输入 Key (键) 和可选的 Value (值)

  9. 选择 Register version


			添加架构版本。

架构版本将显示在版本列表中。如果版本更改了兼容性模式,则版本将标记为检查点。

架构版本比较的示例

当您选择 Compare with previous version (与旧版本进行比较) 时,您将看到先前版本和新版本一起显示。更改的信息将突出显示,如下所示:

  • 黄色:指示已更改信息。

  • Green:指示在最新版本中添加的内容。

  • 红色:表示在最新版本中删除了内容。

您还可以与早期版本进行比较。


			架构版本比较的示例。

删除架构或注册表

删除架构、架构版本或注册表是无法撤消的永久操作。

删除架构

您可能希望使用 AWS 管理控制台或 DeleteSchema 操作 API 删除不再在注册表中使用的架构。

删除一个或多个架构是无法撤消的永久性操作。确保不再需要一个或多个架构。

要从注册表中删除架构,请调用 DeleteSchema 操作 API,并指定 SchemaId 结构以标识架构。

例如:

aws glue delete-schema --schema-id SchemaArn="arn:aws:glue:us-east-2:901234567890:schema/registryName1/schemaname"
aws glue delete-schema --schema-id SchemaName="TestSchema6-deleteschemabyname",RegistryName="default-registry"

AWS Glue 控制台

从 AWS Glue 控制台删除架构:

  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schema registries (架构注册表)

  3. 从注册表列表中选择包含您的架构的注册表。

  4. 通过选中复选框,从列表中选择一个或多个架构。

  5. Action (操作) 菜单中,选择 Delete schema (删除架构)

  6. 在字段中输入文本 Delete 以确认删除。

  7. 选择 Delete.

您指定的架构将从注册表中删除。

删除架构版本

当架构在注册表中累积时,您可能希望使用 AWS 管理控制台或 DeleteSchemaVersions 操作 API 删除不需要的架构版本。删除一个或多个架构版本是无法撤消的永久性操作。确保不再需要架构版本。

删除架构版本时,请注意以下约束:

  • 您无法删除检查点版本。

  • 连续版本的范围不能超过 25 个。

  • 最新架构版本不得处于挂起状态。

指定 SchemaId 结构以标识架构,并将 Versions 指定为要删除的版本范围。有关指定版本或版本范围的更多信息,请参阅DeleteRegistry 操作。您指定的架构版本将从注册表中删除。

在此调用后调用 ListSchemaVersions 操作 API 将列出已删除版本的状态。

例如:

aws glue delete-schema-versions --schema-id SchemaName="TestSchema6",RegistryName="default-registry" --versions "1-1"
aws glue delete-schema-versions --schema-id SchemaArn="arn:aws:glue:us-east-2:901234567890:schema/default-registry/TestSchema6-NON-Existent" --versions "1-1"
  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schema registries (架构注册表)

  3. 从注册表列表中选择包含您的架构的注册表。

  4. 通过选中复选框,从列表中选择一个或多个架构。

  5. Action (操作) 菜单中,选择 Delete schema (删除架构)

  6. 在字段中输入文本 Delete 以确认删除。

  7. 选择 Delete.

您指定的架构版本将从注册表中删除。

删除注册表

当其中包含的架构不应再在该注册表下组织时,您可能希望删除注册表。您将需要将这些架构重新分配给另一个注册表。

删除一个或多个注册表是无法撤消的永久性操作。确保不再需要注册表。

可以使用 AWS CLI 删除默认注册表。

AWS Glue API

要删除整个注册表(包括架构及其所有版本),请调用 DeleteRegistry 操作 API。指定 RegistryId 结构以标识注册表。

例如:

aws glue delete-registry --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1"
aws glue delete-registry --registry-id RegistryName="TestRegistry-deletebyname"

要获取删除操作的状态,您可以在异步调用后调用 GetRegistry API。

AWS Glue 控制台

要从 AWS Glue 控制台中删除注册表,请执行以下操作:

  1. 登录 AWS 管理控制台,并通过以下网址打开 AWS Glue 控制台:https://console.aws.amazon.com/glue/.

  2. 在导航窗格中的 Data catalog (数据目录) 下,选择 Schema registries (架构注册表)

  3. 通过选中一个框,从列表中选择注册表。

  4. Action (操作) 菜单中,选择 Delete registry (删除注册表)

  5. 在字段中输入文本 Delete 以确认删除。

  6. 选择 Delete.

您选择的注册表将从 AWS Glue 中删除。

序列化器的 IAM 示例

对于序列化器,您应创建一个类似于下文中的策略,以便能够为给定架构定义查找 schemaVersionId。请注意,您应具有注册表的读取权限才能读取注册表中的架构。您可以使用 Resource 子句限制可读取的注册表。

代码示例 13:

{ "Sid" : "GetSchemaByDefinition", "Effect" : "Allow", "Action" : [ "glue:GetSchemaByDefinition" ], "Resource" : ["arn:aws:glue:us-east-2:012345678:registry/registryname-1", "arn:aws:glue:us-east-2:012345678:schema/registryname-1/schemaname-1", "arn:aws:glue:us-east-2:012345678:schema/registryname-1/schemaname-2" ] }

此外,您还可以允许创建者通过包括以下额外方法创建新的架构和版本。请注意,您应该能够检查注册表,以便添加/删除/流式传输其中的架构。您可以使用 Resource 子句限制可以检查的注册表。

代码示例 14:

{ "Sid" : "RegisterSchemaWithMetadata", "Effect" : "Allow", "Action" : [ "glue:GetSchemaByDefinition", "glue:CreateSchema", "glue:RegisterSchemaVersion", "glue:PutSchemaVersionMetadata", ], "Resource" : ["arn:aws:glue:us-east-2:012345678:registry/registryname-1", "arn:aws:glue:us-east-2:012345678:schema/registryname-1/schemaname-1", "arn:aws:glue:us-east-2:012345678:schema/registryname-1/schemaname-2" ] }

反串行化器的 IAM 示例

对于反串行化器(使用者端),您应创建一个类似于下文的策略,以允许反串行化器从架构注册表中提取架构以进行反串行化。请注意,您应该能够检查注册表以便提取其中的架构。您可以使用 Resource 子句限制 可以读取的 注册表。但是,如果需要访问所有注册表,则可通过为 ARN 的相应部分指定“*”来实现。

代码示例 15:

{ "Sid" : "GetSchemaVersion", "Effect" : "Allow", "Action" : [ "glue:GetSchemaVersion" ], "Resource" : ["*"] }

使用 AWS PrivateLink 的私有连接

您可以使用 AWS PrivateLink,通过为 AWS Glue 定义接口 VPC 终端节点,将数据创建器的 VPC 连接到 AWS Glue。当您使用 VPC 接口终端节点时,您的 VPC 和 AWS Glue 之间的通信完全在 AWS 网络内进行。有关更多信息,请参阅将 AWS Glue 与 VPC 终端节点结合使用.

访问 AWS CloudWatch 指标

AWS CloudWatch 指标作为 CloudWatch 免费套餐的一部分提供。您可以在 CloudWatch 控制台中访问这些指标。API 级指标包括 CreateSchema(成功和延迟)、GetSchemaByDefinition、(成功和延迟)、GetSchemaVersion(成功和延迟)、RegisterSchemaVersion(成功和延迟)、PutSchemaVersionMetadata(成功和延迟)。资源级指标包括 Registry.ThrottledByLimit、SchemaVersion.ThrottledByLimit、SchemaVersion.Size。