# Registro de esquemas do AWS Glue
**nota**
O registro de esquemas do AWS Glue não é compatível nas seguintes regiões no console do AWS Glue: Oriente Médio (EAU).
Com o registro de esquemas do AWS Glue, você pode descobrir, controlar e evoluir centralmente esquemas de fluxo de dados. O *esquema* define a estrutura e o formato de um registro de dados. Com o registro de esquemas do AWS Glue, você pode gerenciar e aplicar esquemas em suas aplicações de fluxo de dados usando integrações convenientes com o Apache Kafka, [Amazon Managed Streaming for Apache Kafka](https://aws.amazon.com/msk/), [Amazon Kinesis Data Streams](https://aws.amazon.com/kinesis/data-streams/), [Amazon Managed Service for Apache Flink](https://aws.amazon.com/kinesis/data-analytics/) e [AWS Lambda](https://aws.amazon.com/lambda/).
O Schema Registry é compatível com o formato de dados AVRO (v1.11.4), o formato de dados JSON com [formato JSON Schema](https://json-schema.org/) para o esquema (especificações Draft-04, Draft-06 e Draft-07) com validação do esquema JSON usando a [biblioteca do Everit](https://github.com/everit-org/json-schema), Protocol Buffers (Protobuf) versões proto2 e proto3 não compatíveis com `extensions` e `groups`, e compatíveis com a linguagem Java, e outros formatos de dados e linguagens a serem incluídos em breve. Os recursos com suporte incluem compatibilidade, fornecimento de esquema via metadados, registro automático de esquemas, compatibilidade com o IAM e compactação ZLIB opcional para reduzir o armazenamento e a transferência de dados. O registro de esquemas do O registro de esquemas é uma solução sem servidor e de uso gratuito.
O uso de um esquema como um contrato de formato de dados entre produtores e consumidores leva a uma melhor governança e maior qualidade dos dados, e ainda permite que os consumidores de dados sejam resilientes a alterações upstream compatíveis.
O registro de esquemas permite que sistemas diferentes compartilhem um esquema para serialização e desserialização. Por exemplo, suponha que você tenha um produtor e consumidor de dados. O produtor conhece o esquema quando publica os dados. O registro de esquemas fornece um serializador e desserializador para determinados sistemas, como Amazon MSK ou Apache Kafka.
Para obter mais informações, consulte [Como o registro de esquemas funciona](schema-registry-works.md).
**Topics**
+ [Esquemas](#schema-registry-schemas)
+ [Registros](#schema-registry-registries)
+ [Versionamento e compatibilidade de esquema](#schema-registry-compatibility)
+ [Bibliotecas Serde de código aberto](#schema-registry-serde-libraries)
+ [Cotas do registro do esquemas](#schema-registry-quotas)
+ [Como o registro de esquemas funciona](schema-registry-works.md)
+ [Conceitos básicos do registro de esquemas](schema-registry-gs.md)
## Esquemas
O *esquema* define a estrutura e o formato de um registro de dados. Um esquema é uma especificação versionada para publicação, consumo ou datastore confiáveis.
Neste esquema de exemplo para Avro, o formato e a estrutura são definidos pelo layout e nomes de campo, e o formato dos nomes de campo é definido pelos tipos de dados (por exemplo,`string`, `int`).
```
{
"type": "record",
"namespace": "ABC_Organization",
"name": "Employee",
"fields": [
{
"name": "Name",
"type": "string"
},
{
"name": "Age",
"type": "int"
},
{
"name": "address",
"type": {
"type": "record",
"name": "addressRecord",
"fields": [
{
"name": "street",
"type": "string"
},
{
"name": "zipcode",
"type": "int"
}
]
}
}
]
}
```
Neste exemplo de esquema JSON Draft-07 para JSON, o formato é definido pela [organização do esquema JSON](https://json-schema.org/).
```
{
"$id": "https://example.com/person.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Person",
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "The person's first name."
},
"lastName": {
"type": "string",
"description": "The person's last name."
},
"age": {
"description": "Age in years which must be equal to or greater than zero.",
"type": "integer",
"minimum": 0
}
}
}
```
Neste exemplo para Protobuf, o formato é definido pela [versão 2 da linguagem Protocol Buffers (proto2)](https://developers.google.com/protocol-buffers/docs/reference/proto2-spec).
```
syntax = "proto2";
package tutorial;
option java_multiple_files = true;
option java_package = "com.example.tutorial.protos";
option java_outer_classname = "AddressBookProtos";
message Person {
optional string name = 1;
optional int32 id = 2;
optional string email = 3;
enum PhoneType {
MOBILE = 0;
HOME = 1;
WORK = 2;
}
message PhoneNumber {
optional string number = 1;
optional PhoneType type = 2 [default = HOME];
}
repeated PhoneNumber phones = 4;
}
message AddressBook {
repeated Person people = 1;
}
```
## Registros
Um *registro* é um contêiner lógico de esquemas. Os registros permitem que você organize seus esquemas, bem como gerencie o controle de acesso para suas aplicações. Um registro tem um nome do recurso da Amazon (ARN) para permitir que você organize e defina diferentes permissões de acesso para operações de esquema dentro do registro.
Você pode usar o registro padrão ou criar quantos novos registros forem necessários.
**AWS GlueHierarquia do registro de esquemas do**
| |
| --- |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/schema-registry.html) |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/schema-registry.html) |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/schema-registry.html) |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/schema-registry.html) |
## Versionamento e compatibilidade de esquema
Cada esquema pode ter várias versões. O versionamento é regido por uma regra de compatibilidade aplicada em um esquema. As solicitações para registrar novas versões do esquema são verificadas quanto a essa regra pelo registro de esquemas antes de serem bem-sucedidas.
Uma versão de esquema que está marcada como um ponto de verificação é usada para determinar a compatibilidade em registrar novas versões de um esquema. Quando um esquema é criado pela primeira vez, o ponto de verificação padrão é a primeira versão. À medida que o esquema evolui com mais versões, você pode usar a CLI/SDK para alterar o ponto de verificação para uma versão de um esquema usando a API `UpdateSchema` que adere a um conjunto de restrições. No console, editar a definição do esquema ou o modo de compatibilidade alterará o ponto de verificação para a versão mais recente por padrão.
Os modos de compatibilidade permitem controlar como os esquemas podem ou não evoluir ao longo do tempo. Esses modos formam o contrato entre aplicações que produzem e consomem dados. Quando uma nova versão de um esquema é enviada para o registro, a regra de compatibilidade aplicada ao nome do esquema é usada para determinar se a nova versão pode ser aceita. Existem oito modos de compatibilidade: NONE (Nenhum), DISABLED (Desabilitado), BACKWARD (Anterior), BACKWARD\$1ALL (Todas as anteriores), FORWARD (Próxima), FORWARD\$1ALL (Todas as próximas), FULL (Completo), FULL\$1ALL (Completo total).
No formato de dados Avro, os campos podem ser opcionais ou obrigatórios. Um campo opcional é aquele em que o `Type` inclui nulo. Campos obrigatórios não possuem nulo como o `Type`.
No formato de dados Protobuf, os campos podem ser opcionais (inclusive repetidos) ou obrigatórios na sintaxe proto2, enquanto todos os campos são opcionais (inclusive repetidos) na sintaxe proto3. Todas as regras de compatibilidade são determinadas com base no entendimento das especificações de Protocol Buffers, bem como na orientação da [Documentação do Google Protocol Buffers](https://developers.google.com/protocol-buffers/docs/overview#updating).
+ *NONE* (Nenhum): nenhum modo de compatibilidade se aplica. Você pode usar essa opção em cenários de desenvolvimento ou se não souber os modos de compatibilidade que deseja aplicar aos esquemas. Qualquer nova versão adicionada será aceita sem ser submetida a uma verificação de compatibilidade.
+ *DISABLED* (Desabilitado): essa opção de compatibilidade impede o versionamento de um esquema específico. Nenhuma nova versão pode ser adicionada.
+ *BACKWARD* (Anterior): essa opção de compatibilidade é recomendada, pois permite que os consumidores de dados leiam a versão atual e anterior do esquema. Você pode usar essa opção para verificar a compatibilidade com a versão anterior do esquema ao excluir campos ou adicionar campos opcionais. Um caso de uso típico para BACKWARD (Anterior) é quando sua aplicação é criada para o esquema mais recente.
**AVRO**
Por exemplo, suponha que você tenha um esquema definido pelo nome (obrigatório), sobrenome (obrigatório), e-mail (obrigatório) e número de telefone (opcional).
Se a próxima versão do esquema removesse o campo de e-mail obrigatório, isso seria registrado com êxito. A compatibilidade BACKWARD (Anterior) requer que os consumidores sejam capazes de ler a versão atual e anterior do esquema. Seus consumidores poderão ler o novo esquema, pois o campo de e-mail extra de mensagens antigas será ignorado.
Se você tivesse uma nova versão de esquema proposta que adicionasse um campo obrigatório, por exemplo, CEP, isso não seria registrado com êxito com a compatibilidade BACKWARD (Anterior). Seus consumidores na nova versão não conseguiriam ler mensagens antigas antes da alteração do esquema, pois elas não teriam o campo CEP necessário. No entanto, se o campo CEP fosse definido como opcional no novo esquema, a versão proposta seria registrada com sucesso, pois os consumidores poderiam ler o esquema antigo sem o campo de CEP opcional.
**JSON**
Por exemplo, suponha que você tenha uma versão do esquema definida pelo nome (opcional), sobrenome (opcional), e-mail (opcional) e número de telefone (opcional).
Se a próxima versão do esquema adicionasse a propriedade de número de telefone opcional, isso seria registrado com êxito, desde que a versão do esquema original não permitisse nenhuma propriedade adicional definindo o campo `additionalProperties` como false. A compatibilidade BACKWARD (Anterior) requer que os consumidores sejam capazes de ler a versão atual e anterior do esquema. Seus consumidores poderão ler dados produzidos com o esquema original onde a propriedade de número de telefone não existe.
Se você tiver uma nova versão de esquema proposta que adiciona a propriedade de número de telefone opcional, isso não é registrado com êxito com a compatibilidade BACKWARD (Anterior) quando a versão original do esquema define o campo `additionalProperties` como true, ou seja, permitindo qualquer propriedade adicional. Seus consumidores na nova versão não conseguiriam ler mensagens antigas antes da alteração do esquema, pois não podem ler dados com a propriedade número de telefone em um tipo diferente, por exemplo string em vez de número.
**PROTOBUF**
Por exemplo, suponha que você tenha uma versão do esquema definida por uma Mensagem `Person` com campos `first name` (obrigatório), `last name` (obrigatório), `email` (obrigatório) e `phone number` (opcional) sob sintaxe proto2.
Semelhante a cenários AVRO, se a próxima versão do esquema removesse o campo de `email` obrigatório, isso seria registrado com êxito. A compatibilidade BACKWARD (Anterior) requer que os consumidores sejam capazes de ler a versão atual e anterior do esquema. Seus consumidores poderão ler o novo esquema, pois o campo de `email` extra de mensagens antigas será ignorado.
Se você tivesse uma nova versão de esquema proposta que adicionasse um campo obrigatório, por exemplo, `zip code`, isso não seria registrado com êxito com a compatibilidade BACKWARD (Anterior). Seus consumidores na nova versão não conseguiriam ler mensagens antigas antes da alteração do esquema, pois elas não teriam o campo `zip code` necessário. No entanto, se o campo `zip code` fosse definido como opcional no novo esquema, a versão proposta seria registrada com sucesso, pois os consumidores poderiam ler o esquema antigo sem o campo de `zip code` opcional.
No caso de um caso de uso gRPC, adicionar novo serviço RPC ou método RPC é uma alteração compatível com versões anteriores. Por exemplo, suponha que você tenha uma versão do esquema definida por um serviço RPC `MyService` com dois métodos RPC `Foo` e `Bar`.
Se a próxima versão do esquema adicionar um novo método RPC chamado `Baz`, isso seria registrado com sucesso. Seus consumidores poderão ler dados produzidos com o esquema original de acordo com a compatibilidade BACKWARD pois o método RPC recém-adicionado `Baz` é opcional.
Se você tivesse uma nova versão de esquema proposta que removesse o método PRC existente `Foo`, isso não seria registrado com êxito com a compatibilidade BACKWARD. Seus consumidores na nova versão não conseguiriam ler mensagens antigas antes da alteração do esquema, pois não conseguem entender e ler dados com o método RPC `Foo` inexistente em uma aplicação gRPC.
+ *BACKWARD\$1ALL* (Todas as anteriores): essa opção de compatibilidade é recomendada, pois permite que os consumidores de dados leiam a versão atual e todas as anteriores do esquema. Você pode usar essa opção para verificar a compatibilidade com todas as versões anteriores do esquema ao excluir campos ou adicionar campos opcionais.
+ *FORWARD* (Próxima): essa opção de compatibilidade permite que os receptores de dados leiam a versão atual e as versões subsequentes do esquema, mas não necessariamente versões mais recentes. Você pode usar essa opção para verificar a compatibilidade com a última versão do esquema ao adicionar campos ou excluir campos opcionais. Um caso de uso típico para FORWARD (Próxima) é quando sua aplicação é criada para um esquema anterior e deve ser capaz de processar um esquema mais recente.
**AVRO**
Por exemplo, suponha que você tenha uma versão do esquema definida pelo nome (obrigatório), sobrenome (obrigatório) e e-mail (opcional).
Se você tivesse uma nova versão do esquema que adicionasse um campo obrigatório, por exemplo, número de telefone, isso seria registrado com sucesso. A compatibilidade FORWARD (Próxima) requer que os consumidores sejam capazes de ler dados produzidos com o novo esquema usando ainda a versão anterior.
Se você tivesse uma nova versão de esquema proposta que excluísse o campo de nome obrigatório, isso não seria registrado com êxito com a compatibilidade FORWARD (Posterior). Seus consumidores na versão anterior não seriam capazes de ler os esquemas propostos, pois eles não teriam o campo de nome obrigatório. No entanto, se o campo de nome fosse originalmente opcional, então o novo esquema proposto seria registrado com sucesso, pois os consumidores poderiam ler dados com base no novo esquema que não tem o campo de nome opcional.
**JSON**
Por exemplo, suponha que você tenha uma versão do esquema definida pelo nome (opcional), sobrenome (opcional), e-mail (opcional) e número de telefone (opcional).
Se a próxima versão do esquema removesse a propriedade de número de telefone opcional, isso seria registrado com êxito, desde que a versão do esquema original não permitisse nenhuma propriedade adicional definindo o campo `additionalProperties` como false. A compatibilidade FORWARD (Próxima) requer que os consumidores sejam capazes de ler dados produzidos com o novo esquema usando ainda a versão anterior.
Se você tiver uma versão de esquema proposta que exclui a propriedade número de telefone opcional, isso não é registrado com êxito com a compatibilidade FORWARD (Próxima) quando a nova versão do esquema define o campo `additionalProperties` como true, ou seja, permitindo qualquer propriedade adicional. Seus consumidores na versão anterior não conseguiriam ler mensagens antigas antes da alteração do esquema, pois não poderiam ler dados com a propriedade número de telefone em um tipo diferente, por exemplo string em vez de número.
**PROTOBUF**
Por exemplo, suponha que você tenha uma versão do esquema definida por uma Mensagem `Person` com campos `first name` (obrigatório), `last name` (obrigatório) e `email` (opcional) sob sintaxe proto2.
Semelhante a cenários AVRO, se você tivesse uma nova versão do esquema que adicionasse um campo obrigatório, por exemplo, `phone number`, isso seria registrado com sucesso. A compatibilidade FORWARD (Próxima) requer que os consumidores sejam capazes de ler dados produzidos com o novo esquema usando ainda a versão anterior.
Se você tivesse uma nova versão de esquema proposta que excluísse o campo de `first name`, isso não seria registrado com êxito com a compatibilidade FORWARD. Seus consumidores na versão anterior não seriam capazes de ler os esquemas propostos, pois eles não teriam o campo de `first name` obrigatório. No entanto, se o campo de `first name` fosse originalmente opcional, então o novo esquema proposto seria registrado com sucesso, pois os consumidores poderiam ler dados com base no novo esquema que não tem o campo de `first name` opcional.
No caso de um caso de uso gRPC, remover um serviço RPC ou método RPC é uma alteração compatível com o encaminhamento. Por exemplo, suponha que você tenha uma versão do esquema definida por um serviço RPC `MyService` com dois métodos RPC `Foo` e `Bar`.
Se a próxima versão do esquema excluir o método RPC existente chamado `Foo`, isso seria registrado com sucesso de acordo com a compatibilidade FORWARD, pois os consumidores podem ler dados produzidos com o novo esquema usando a versão anterior. Se você tivesse uma nova versão de esquema proposta que adicionasse o método RPC `Baz`, isso não seria registrado com êxito com a compatibilidade FORWARD. Seus consumidores na versão anterior não seriam capazes de ler os esquemas propostos, pois eles não teriam o método RPC ausente `Baz`.
+ *FORWARD\$1ALL* (Todas as próximas): essa opção de compatibilidade permite que os consumidores leiam dados escritos por produtores de qualquer novo esquema registrado. Você pode usar essa opção quando precisar adicionar campos ou excluir campos opcionais e verificar a compatibilidade com todas as versões anteriores do esquema.
+ *FULL* (Completo): essa opção de compatibilidade permite que os consumidores leiam dados gravados por produtores usando a versão anterior ou seguinte do esquema, mas não versões anteriores ou posteriores. Você pode usar essa opção para verificar a compatibilidade com a última versão do esquema ao adicionar ou remover campos opcionais.
+ *FULL\$1ALL* (Completo total): essa opção de compatibilidade permite que os receptores de dados leiam dados gravados por produtores usando todas as versões de esquema anteriores. Você pode usar essa opção para verificar a compatibilidade com todas as versões anteriores do esquema ao adicionar ou remover campos opcionais.
## Bibliotecas Serde de código aberto
AWSA fornece bibliotecas Serde de código aberto como um framework para serialização e desserialização de dados. O design de código aberto dessas bibliotecas permite que aplicações e frameworks comuns de código aberto ofereçam suporte a elas em seus projetos.
Para obter mais detalhes sobre como as bibliotecas Serde funcionam, consulte [Como o registro de esquemas funciona](schema-registry-works.md).
## Cotas do registro do esquemas
As cotas, também conhecidas como limites na AWS, são os valores máximos para recursos, ações e itens na sua conta da AWS. A seguir estão os limites flexíveis para o registro de esquemas no AWS Glue.
**Pares de chave-valor de metadados de versão de esquema**
Você pode ter até dez pares de chave-valor por SchemaVersion por região da AWS.
Você pode visualizar ou definir os pares de metadados de chave-valor usando o [Ação QuerySchemaVersionMetadata (Python: query\$1schema\$1version\$1metadata)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-QuerySchemaVersionMetadata) ou APIs do [Ação PutSchemaVersionMetadata (Python: put\$1schema\$1version\$1metadata)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-PutSchemaVersionMetadata).
A seguir estão os limites rígidos para o registro de esquemas no AWS Glue.
**Registros**
É possível ter até 100 registros por região da AWS para esta conta.
**SchemaVersion**
É possível ter até 10.000 versões de esquema por região da AWS para esta conta.
Cada novo esquema cria uma nova versão do esquema, portanto você poderá, teoricamente, ter até 10.000 esquemas por conta por região, se cada esquema tiver apenas uma versão.
**Cargas úteis de esquema**
Há um limite de tamanho de 170 KB para cargas úteis de esquema.
# Como o registro de esquemas funciona
Esta seção descreve como os processos de serialização e desserialização no registro de esquemas funcionam.
1. Registrar um esquema: se o esquema ainda não existir no registro, ele pode ser registrado com um nome de esquema igual ao nome do destino (por exemplo, test\$1topic, test\$1stream, prod\$1firehose) ou o produtor pode fornecer um nome personalizado para ele. Os produtores também podem adicionar pares de chave-valor ao esquema como metadados, como a fonte: msk\$1kafka\$1topic\$1a ou aplicar tags da AWS para esquemas na criação do esquema. Depois que um esquema é registrado, o registro de esquemas retorna o ID da versão do esquema para o serializador. Se o esquema existir, mas o serializador estiver usando uma nova versão que não existe, o registro de esquemas verificará a referência do esquema a uma regra de compatibilidade, para garantir que a nova versão seja compatível antes de registrá-la como uma nova versão.
Existem dois métodos de registro de um esquema: manual e automático. Você pode registrar um esquema manualmente por meio do console do AWS Glue ou CLI/SDK.
Quando o registro automático é ativado nas configurações do serializador, o registro automático do esquema é realizado. Se `REGISTRY_NAME` não for fornecido nas configurações do produtor, o registro automático registrará a nova versão do esquema no registro padrão (default-registry). Consulte [Instalar as bibliotecas SerDe](schema-registry-gs-serde.md) para obter informações sobre como especificar a propriedade de registro automático.
1. O serializador valida registros de dados em relação ao esquema: quando a aplicação que produz os dados registra seu esquema, o serializador do registro de esquemas valida que o registro sendo produzido pela aplicação é estruturado com os campos e os tipos de dados correspondentes a um esquema registrado. Se o esquema do registro não corresponder a um esquema registrado, o serializador retornará uma exceção e a aplicação falhará em entregar o registro ao destino.
Se nenhum esquema existir e o nome do esquema não for fornecido por meio das configurações do produtor, o esquema será criado com o mesmo nome que o nome do tópico (se Apache Kafka ou Amazon MSK) ou nome da transmissão (se Kinesis Data Streams).
Cada registro tem uma definição de esquema e dados. A definição de esquema é consultada em relação aos esquemas e versões existentes no registro de esquemas.
Por padrão, os produtores armazenam em cache as definições de esquema e IDs de versão de esquemas dos esquemas registrados. Se a definição da versão do esquema de um registro não corresponder ao que está disponível no cache, o produtor tentará validar o esquema com o registro de esquemas. Se a versão do esquema for válida, seu ID de versão e definição serão armazenados em cache localmente no produtor.
Você pode ajustar o período de cache padrão (24 horas) dentro das propriedades opcionais do produtor na etapa n.º 3 de [Instalar as bibliotecas SerDe](schema-registry-gs-serde.md).
1. Serializar e entregar registros: se o registro estiver em conformidade com o esquema, o serializador decorará cada registro com o ID da versão do esquema, serializará o registro com base no formato de dados selecionado (AVRO, JSON ou Protobuf. Outros formatos em breve), compactará o registro (configuração opcional do produtor) e o entregará ao destino.
1. Os consumidores desserializam os dados: os consumidores que leem esses dados usam a biblioteca de desserialização do registro de esquemas, que analisa o ID da versão do esquema na carga útil do registro.
1. O desserializador pode solicitar o esquema do registro do esquemas: se esta for a primeira vez que o desserializador viu registros com um ID de versão do esquema específico, o desserializador, usando o ID da versão do esquema, solicitará o esquema do registro do esquemas e o armazenará localmente no consumidor. Se o registro de esquemas não puder desserializar o registro, o consumidor poderá registrar em log os dados do registro e seguir em frente, ou interromper a aplicação.
1. O desserializador usa o esquema para desserializar o registro: quando o desserializador recupera o ID da versão do esquema do registro do esquemas, ele descompacta o registro (se o registro enviado pelo produtor for compactado) e usa o esquema para o desserializar. Então, a aplicação processa o registro.
**nota**
Criptografia: seus clientes se comunicam com o registro de esquemas por meio de chamadas de API que criptografam dados em trânsito usando criptografia TLS em HTTPS. Os esquemas armazenados no registro de esquemas são sempre criptografados em repouso usando uma chave do AWS Key Management Service (AWS KMS) gerenciada por um serviço.
**nota**
Autorização do usuário: o registro de esquemas é compatível com políticas do IAM baseadas em identidade.
# Conceitos básicos do registro de esquemas
As seções a seguir fornecem uma visão geral e orientações sobre como configurar e usar o registro de esquemas. Para obter informações sobre conceitos e componentes do registro de esquemas, consulte [Registro de esquemas do AWS Glue](schema-registry.md).
**Topics**
+ [Instalar as bibliotecas SerDe](schema-registry-gs-serde.md)
+ [Integração com o registro de esquemas do AWS Glue](schema-registry-integrations.md)
+ [Migração de um registro de esquemas de terceiros para o registro de esquemas do AWS Glue](schema-registry-integrations-migration.md)
# Instalar as bibliotecas SerDe
As bibliotecas SerDe fornecem um framework para serialização e desserialização de dados.
Você instalará o serializador de código aberto para suas aplicações que produzem dados (coletivamente os “serializadores”). O serializador manipula serialização, compactação e interação com o registro de esquemas. O serializador extrai automaticamente o esquema de um registro sendo gravado em um destino compatível com o registro de esquemas, como o Amazon MSK. Da mesma forma, você instalará o desserializador de código aberto em suas aplicações que consomem dados.
# Implementação de Java
**nota**
Pré-requisitos: antes de concluir as etapas a seguir, é necessário ter um cluster do Amazon Managed Streaming for Apache Kafka (Amazon MSK) ou do Apache Kafka em execução. Seus produtores e consumidores precisam estar em execução em Java 8 ou superior.
Para instalar as bibliotecas em produtores e consumidores:
1. Dentro dos arquivos pom.xml, tanto dos produtores quanto dos consumidores, adicione essa dependência com o código abaixo:
```
software.amazon.glueschema-registry-serde1.1.5
```
Como alternativa, você pode clonar o [repositório do registro de esquemas do AWS Glue do GitHub](https://github.com/awslabs/aws-glue-schema-registry).
1. Configure seus produtores com estas propriedades obrigatórias:
```
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, GlueSchemaRegistryKafkaSerializer.class.getName());
props.put(AWSSchemaRegistryConstants.AWS_REGION, "us-east-2");
properties.put(AWSSchemaRegistryConstants.DATA_FORMAT, "JSON"); // OR "AVRO"
```
Se não houver esquemas existentes, o registro automático precisará ser ativado (próxima etapa). Se você tiver um esquema que gostaria de aplicar, substitua “my-schema” (meu esquema) pelo nome do seu esquema. Além disso, o “registry-name” (nome do registro) deve ser fornecido se o registro automático do esquema estiver desativado. Se o esquema é criado sob o “default-registry” (registro padrão), o nome do registro pode ser omitido.
1. (Opcional) defina qualquer uma destas propriedades opcionais do produtor. Para obter descrições detalhadas das propriedades, consulte [o arquivo ReadMe](https://github.com/awslabs/aws-glue-schema-registry/blob/master/README.md).
```
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
```
O registro automático registra a versão do esquema no registro padrão (“default-registry”). Se um `SCHEMA_NAME` não for especificado na etapa anterior, então o nome do tópico será inferido como `SCHEMA_NAME`.
Consulte [Versionamento e compatibilidade de esquema](schema-registry.md#schema-registry-compatibility), para obter mais informações sobre os modos de compatibilidade.
1. Configure seus consumidores com estas propriedades obrigatórias:
```
props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class.getName());
props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, GlueSchemaRegistryKafkaDeserializer.class.getName());
props.put(AWSSchemaRegistryConstants.AWS_REGION, "us-east-2"); // Pass an Região da AWS
props.put(AWSSchemaRegistryConstants.AVRO_RECORD_TYPE, AvroRecordType.GENERIC_RECORD.getName()); // Only required for AVRO data format
```
1. (Opcional) defina essas propriedades opcionais do consumidor. Para obter descrições detalhadas das propriedades, consulte [o arquivo ReadMe](https://github.com/awslabs/aws-glue-schema-registry/blob/master/README.md).
```
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
```
# Implementação de C\$1
**nota**
Pré-requisitos: antes de concluir as etapas a seguir, é necessário ter um cluster do Amazon Managed Streaming for Apache Kafka (Amazon MSK) ou do Apache Kafka em execução. Seus produtores e consumidores precisam estar em execução em .NET 8.0 ou superior.
## Instalação
Para aplicativos C\$1, instale o pacote AWS Glue Schema Registry SerDe NuGet usando um dos métodos a seguir:
**.NET CLI:**
Para instalar o pacote, execute o comando a seguir:
```
dotnet add package Aws.Glue.SchemaRegistry --version 1.0.0-
```
onde `` poderia ser `1.0.0-linux-x64`, `1.0.0-linux-musl-x64` ou `1.0.0-linux-arm64`
**PackageReference (em seu arquivo .csproj):**
Adicione o seguinte ao seu arqruivo de projeto:
```
```
onde `` poderia ser `1.0.0-linux-x64`, `1.0.0-linux-musl-x64` ou `1.0.0-linux-arm64`
## Definição do arquivo de configuração
Crie um arquivo de propriedades de configuração (por exemplo, `gsr-config.properties`) com as configurações necessárias:
**Configuração mínima:**
A seguir você verá um exemplo de configuração mínima:
```
region=us-east-1
registry.name=default-registry
dataFormat=AVRO
schemaAutoRegistrationEnabled=true
```
## Usando a biblioteca cliente C\$1 Glue Schema para Kafka SerDes
**Uso do serializador de amostra:**
O exemplo a seguir mostra como usar o serializador:
```
private static readonly string PROTOBUF_CONFIG_PATH = "";
var protobufSerializer = new GlueSchemaRegistryKafkaSerializer(PROTOBUF_CONFIG_PATH);
var serialized = protobufSerializer.Serialize(message, message.Descriptor.FullName);
// send serialized bytes to Kafka using producer.Produce(serialized)
```
**Uso do desserializador de amostra:**
O exemplo a seguir mostra como usar o desserializador:
```
private static readonly string PROTOBUF_CONFIG_PATH = "";
var dataConfig = new GlueSchemaRegistryDataFormatConfiguration(
new Dictionary
{
{
GlueSchemaRegistryConstants.ProtobufMessageDescriptor, message.Descriptor
}
}
);
var protobufDeserializer = new GlueSchemaRegistryKafkaDeserializer(PROTOBUF_CONFIG_PATH, dataConfig);
// read message from Kafka using serialized = consumer.Consume()
var deserializedObject = protobufDeserializer.Deserialize(message.Descriptor.FullName, serialized);
```
## Usando a biblioteca cliente C\$1 Glue Schema para KafkaFlow para SerDes
**Uso do serializador de amostra:**
O exemplo a seguir mostra como configurar o KafkaFlow com o serializador:
```
services.AddKafka(kafka => kafka
.UseConsoleLog()
.AddCluster(cluster => cluster
.WithBrokers(new[] { "localhost:9092" })
.AddProducer(producer => producer
.DefaultTopic("customer-events")
.AddMiddlewares(m => m
.AddSerializer>(
() => new GlueSchemaRegistryKafkaFlowProtobufSerializer("config/gsr-config.properties")
)
)
)
)
);
```
**Uso do desserializador de amostra:**
O exemplo a seguir mostra como configurar o KafkaFlow com o desserializador:
```
.AddConsumer(consumer => consumer
.Topic("customer-events")
.WithGroupId("customer-group")
.WithBufferSize(100)
.WithWorkersCount(10)
.AddMiddlewares(middlewares => middlewares
.AddDeserializer>(
() => new GlueSchemaRegistryKafkaFlowProtobufDeserializer("config/gsr-config.properties")
)
.AddTypedHandlers(h => h.AddHandler())
)
)
```
## Propriedades opcionais do produtor
Você pode estender seu arquivo de configuração com propriedades opcionais adicionais:
```
# Auto-registration (if not passed, uses "false")
schemaAutoRegistrationEnabled=true
# Schema name (if not passed, uses topic name)
schema.name=my-schema
# Registry name (if not passed, uses "default-registry")
registry.name=my-registry
# Cache settings
cacheTimeToLiveMillis=86400000
cacheSize=200
# Compatibility mode (if not passed, uses BACKWARD)
compatibility=FULL
# Registry description
description=This registry is used for several purposes.
# Compression (if not passed, records are sent uncompressed)
compressionType=ZLIB
```
## Formatos de dados suportados
As implementações Java e C\$1 são compatíveis com os mesmos formatos de dados:
+ *AVRO*: formato binário Apache Avro
+ *JSON*: formato do esquema JSON
+ *PROTOBUF*: formato Protocol Buffers
## Observações
+ Para começar a usar a biblioteca, visite [https://www.nuget.org/packages/AWS.Glue.SchemaRegistry](https://www.nuget.org/packages/AWS.Glue.SchemaRegistry)
+ O código-fonte está disponível em: [https://github.com/awslabs/aws-glue-schema-registry](https://github.com/awslabs/aws-glue-schema-registry)
# Criar um registro
Você pode usar o registro padrão ou criar quantos novos registros forem necessários usando as APIS do AWS Glue ou o console do AWS Glue.
**AWS GlueAPIs do**
Você pode usar estas etapas para executar essa tarefa usando as APIs do AWS Glue.
Para usar a AWS CLI para APIs do registro de esquemas do AWS Glue, certifique-se de atualizar a AWS CLI para a versão mais recente.
Para adicionar um novo registro, use a API do [Ação CreateRegistry (Python: create\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-CreateRegistry). Especifique `RegistryName` como o nome do registro a ser criado, com um comprimento máximo de 255, contendo apenas letras, números, hífens, sublinhados, cifrões ou marcas de hash.
Especifique `Description` como uma string com não mais do que 2.048 bytes de comprimento, correspondente ao [padrão de string com várias linhas de endereço URI](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-api-common.html#aws-glue-api-common-_string-patterns).
Como alternativa, especifique um ou mais `Tags` para seu registro, como uma matriz de mapa de pares de chave-valor.
```
aws glue create-registry --registry-name registryName1 --description description
```
Quando seu registro é criado, ele recebe um nome do recurso da Amazon (ARN), que você pode visualizar no `RegistryArn` da resposta da API. Agora que você criou um registro, crie um ou mais esquemas para esse registro.
**AWS GlueConsole do**
Para adicionar um novo registro no console do AWS Glue:
1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema registries** (Registros de esquemas).
1. Escolha **Add registry** (Adicionar registro).
1. Digite um **Registry name** (Nome de registro) para o registro composto por letras, números, hifens ou sublinhados. Esse nome não pode ser alterado.
1. Digite uma **Description** (Descrição) (opcional) para o registro.
1. Opcionalmente, aplique uma ou mais tags ao registro. Escolha **Add new tag** (Adicionar nova tag), especifique um **Tag key** (Chave de tag) e, opcionalmente, um **Tag value** (Valor da tag).
1. Escolha **Add registry** (Adicionar registro).
![\[Exemplo de criação de um registro.\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/schema_reg_create_registry.png)
Quando seu registro é criado, ele recebe um nome do recurso da Amazon (ARN), que você pode visualizar escolhendo o registro na lista em **Schema registries** (Registros de esquemas). Agora que você criou um registro, crie um ou mais esquemas para esse registro.
# Lidar com um registro específico (JAVA POJO) para JSON
Você pode usar um plain old Java object (POJO) e transmitir o objeto como um registro. Isso é semelhante à noção de um registro específico no AVRO. O [mbknor-jackson-jsonschema](https://github.com/mbknor/mbknor-jackson-jsonSchema) pode gerar um esquema JSON para o POJO transmitido. Essa biblioteca também pode injetar informações adicionais no esquema JSON.
A biblioteca do registro de esquemas do AWS Glue usa o campo “className” injetado no esquema para fornecer um nome de classe totalmente classificado. O campo “className” é usado pelo desserializador para desserializar em um objeto dessa classe.
```
Example class :
@JsonSchemaDescription("This is a car")
@JsonSchemaTitle("Simple Car Schema")
@Builder
@AllArgsConstructor
@EqualsAndHashCode
// Fully qualified class name to be added to an additionally injected property
// called className for deserializer to determine which class to deserialize
// the bytes into
@JsonSchemaInject(
strings = {@JsonSchemaString(path = "className",
value = "com.amazonaws.services.schemaregistry.integrationtests.generators.Car")}
)
// List of annotations to help infer JSON Schema are defined by https://github.com/mbknor/mbknor-jackson-jsonSchema
public class Car {
@JsonProperty(required = true)
private String make;
@JsonProperty(required = true)
private String model;
@JsonSchemaDefault("true")
@JsonProperty
public boolean used;
@JsonSchemaInject(ints = {@JsonSchemaInt(path = "multipleOf", value = 1000)})
@Max(200000)
@JsonProperty
private int miles;
@Min(2000)
@JsonProperty
private int year;
@JsonProperty
private Date purchaseDate;
@JsonProperty
@JsonFormat(shape = JsonFormat.Shape.NUMBER)
private Date listedDate;
@JsonProperty
private String[] owners;
@JsonProperty
private Collection serviceChecks;
// Empty constructor is required by Jackson to deserialize bytes
// into an Object of this class
public Car() {}
}
```
# Criar um esquema
Você pode criar um esquema usando as APIs do AWS Glue ou o console do AWS Glue.
**AWS GlueAPIs do**
Você pode usar estas etapas para executar essa tarefa usando as APIs do AWS Glue.
Para adicionar um novo esquema, use a API [Ação CreateSchema (Python: create\$1esquema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-CreateSchema).
Especifique uma estrutura `RegistryId` para indicar um registro para o esquema. Ou omita o `RegistryId` para usar o registro padrão.
Especifique um `SchemaName` consistindo em letras, números, hifens ou sublinhados e `DataFormat` como **AVRO** ou **JSON**. O `DataFormat`, uma vez definido em um esquema, não pode ser alterado.
Especifique um modo de `Compatibility`:
+ *Backward (Anterior) (recomendado)*: o consumidor pode ler a versão atual e a anterior.
+ *Backward all (Todas as anteriores)*: o consumidor pode ler a versão atual e todas as anteriores.
+ *Forward (Próxima)*: o consumidor pode ler a versão atual e a subsequente.
+ *Forward all (Todas as próximas)*: o consumidor pode ler a versão atual e todas as subsequentes.
+ *Full (Completo)*: combinação de Backward e Forward.
+ *Full all (Completo total)*: combinação de Backward all e Forward all.
+ *None (Nenhum)*: nenhuma verificação de compatibilidade é realizada.
+ *Disabled (Desabilitado)*: impede qualquer versionamento para esse esquema.
Opcionalmente, especifique `Tags` para seu esquema.
Especifique uma `SchemaDefinition` para definir o esquema no formato de dados Avro, JSON ou Protobuf. Consulte os exemplos.
Para o formato de dados 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\"} ]}"
```
Para o formato de dados JSON:
```
aws glue create-schema --registry-id RegistryName="registryName" --schema-name testSchemaJson --compatibility NONE --data-format JSON --schema-definition "{\"$schema\": \"http://json-schema.org/draft-07/schema#\",\"type\":\"object\",\"properties\":{\"f1\":{\"type\":\"string\"}}}"
```
```
aws glue create-schema --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName" --schema-name testSchemaJson --compatibility NONE --data-format JSON --schema-definition "{\"$schema\": \"http://json-schema.org/draft-07/schema#\",\"type\":\"object\",\"properties\":{\"f1\":{\"type\":\"string\"}}}"
```
Para o formato de dados Protobuf:
```
aws glue create-schema --registry-id RegistryName="registryName" --schema-name testSchemaProtobuf --compatibility NONE --data-format PROTOBUF --schema-definition "syntax = \"proto2\";package org.test;message Basic { optional int32 basic = 1;}"
```
```
aws glue create-schema --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName" --schema-name testSchemaProtobuf --compatibility NONE --data-format PROTOBUF --schema-definition "syntax = \"proto2\";package org.test;message Basic { optional int32 basic = 1;}"
```
**AWS GlueConsole do**
Para adicionar um novo esquema usando o console do AWS Glue:
1. Faça login no Console de Gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema** (Esquema).
1. Escolha **Add schema** (Adicionar esquema).
1. Digite um **Schema name** (Nome do esquema), consistindo em letras, números, hifens, sublinhados, cifrões ou marcas de hash. Esse nome não pode ser alterado.
1. Escolha o **Registry** (Registro) em que o esquema será armazenado no menu suspenso. O registro pai não pode ser alterado após a criação.
1. Deixe **Data format** (Formato de dados) como *Apache Avro* ou *JSON*. Esse formato se aplica a todas as versões desse esquema.
1. Escolha um **Compatibility mode** (Modo de compatibilidade).
+ *Backward (Anterior) (recomendado)*: o receptor pode ler a versão atual e a anterior.
+ *Backward all (Todas as anteriores)*: o receptor pode ler a versão atual e todas as anteriores.
+ *Forward (Próxima)*: o remetente pode gravar a versão atual e a anterior.
+ *Forward all (Todas as próximas)*: o remetente pode gravar a versão atual e todas as anteriores.
+ *Full (Completo)*: combinação de Backward e Forward.
+ *Full all (Completo total)*: combinação de Backward All e Forward All.
+ *None (Nenhum)*: nenhuma verificação de compatibilidade é realizada.
+ *Disabled (Desabilitado)*: impede qualquer versionamento para esse esquema.
1. Insira uma **Description** (Descrição) opcional de até 250 caracteres para o registro.
![\[Exemplo de criação de um esquema.\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/schema_reg_create_schema.png)
1. Opcionalmente, aplique uma ou mais tags ao esquema. Escolha **Add new tag** (Adicionar nova tag), especifique um **Tag key** (Chave de tag) e, opcionalmente, um **Tag value** (Valor da tag).
1. Na caixa **First schema version** (Primeira versão do esquema), insira ou cole o esquema inicial.
Para o formato Avro, consulte [Trabalhar com o formato de dados Avro](#schema-registry-avro)
Para o formato JSON, consulte [Trabalhar com o formato de dados JSON](#schema-registry-json)
1. Opcionalmente, escolha **Add metadata** (Adicionar metadados) para adicionar metadados de versão para anotar ou classificar a versão do esquema.
1. Selecione **Create schema and version** (Criar esquema e versão).
![\[Exemplo de criação de um esquema.\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/schema_reg_create_schema2.png)
O esquema é criado e aparece na lista em **Schemas** (Esquemas).
## Trabalhar com o formato de dados Avro
O Avro fornece serviços de serialização e troca de dados. O Avro armazena a definição de dados no formato JSON facilitando a leitura e interpretação. Os dados em si são armazenados em formato binário.
Para obter informações sobre como definir um esquema do Apache Avro, consulte a [especificação do Apache Avro](http://avro.apache.org/docs/current/spec.html).
## Trabalhar com o formato de dados JSON
Os dados podem ser serializados com o formato JSON. O [formato do esquema JSON](https://json-schema.org/) define o padrão para o formato de esquema JSON.
# Atualizar um esquema ou registro
Uma vez criados, você pode editar seus esquemas, versões de esquema ou registro.
## Atualizar um registro
Você pode atualizar um registro usando as APIs do AWS Glue ou o console do AWS Glue. O nome de um registro existente não pode ser editado. Você pode editar a descrição de um registro.
**AWS GlueAPIs do**
Para atualizar um registro existente, use a API [Ação UpdateRegistry (Python: update\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-UpdateRegistry).
Especifique uma estrutura `RegistryId` para indicar o registro que você deseja atualizar. Informe uma `Description` para alterar a descrição de um registro.
```
aws glue update-registry --description updatedDescription --registry-id RegistryArn="arn:aws:glue:us-east-2:901234567890:registry/registryName1"
```
**AWS GlueConsole do**
Para atualizar um registro usando o console do AWS Glue:
1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema registries** (Registros de esquemas).
1. Escolha um registro na lista de registros, marcando a caixa correspondente.
1. No menu **Action** (Ação), escolha **Edit registry** (Editar registro).
# Atualizar um esquema
Você pode atualizar a descrição ou a configuração de compatibilidade de um esquema.
Para atualizar um esquema existente, use a API [Ação UpdateSchema (Python: update\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-UpdateSchema).
Especifique uma estrutura `SchemaId` para indicar o esquema que você deseja atualizar. Um de `VersionNumber` ou `Compatibility` tem de ser fornecido.
Exemplo de código 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
```
# Adicionar uma versão de esquema
Quando você adiciona uma versão de esquema, precisa comparar as versões para se certificar de que o novo esquema será aceito.
Para adicionar uma nova versão a um esquema existente, use a API [Ação RegisterSchemaVersion (Python: register\$1schema\$1version)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-RegisterSchemaVersion).
Especifique um estrutura `SchemaId` para indicar o esquema no qual você deseja adicionar uma versão e uma `SchemaDefinition` para definir o esquema.
Exemplo de código 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. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema** (Esquema).
1. Escolha o esquema na lista de esquemas, marcando a caixa correspondente.
1. Escolha um ou mais esquemas na lista, marcando as caixas.
1. No menu **Action** (Ação), escolha **Register new version** (Registrar nova versão).
1. Na caixa **New version** (Nova versão), insira ou cole seu novo esquema.
1. Escolha **Compare with previous version** (Comparar com a versão anterior) para ver as diferenças em relação à versão anterior do esquema.
1. Opcionalmente, escolha **Add metadata** (Adicionar metadados) para adicionar metadados de versão para anotar ou classificar a versão do esquema. Digite a **Key** (Chave) e o **Value** (Valor) opcional.
1. Escolha **Register version** (Registrar versão).
![\[Adicionar uma versão de esquema.\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/schema_reg_add_schema_version.png)
As versões dos esquemas aparecem na lista de versões. Se a versão alterou o modo de compatibilidade, ela será marcada como um ponto de verificação.
## Exemplo de comparação de versões de esquema
Quando você escolher **Compare with previous version** (Comparar com a versão anterior), você verá a versão nova e a anterior exibidas juntas. As informações alteradas serão destacadas da seguinte forma:
+ *Amarelo*: indica informações alteradas.
+ *Verde*: indica o conteúdo adicionado na versão mais recente.
+ *Vermelho*: indica o conteúdo removido da versão mais recente.
Você também pode comparar com versões anteriores.
![\[Exemplo de comparação de versões de esquema.\]](http://docs.aws.amazon.com/pt_br/glue/latest/dg/images/schema_reg_version_comparison.png)
# Excluir um esquema ou registro
Excluir um esquema, uma versão de esquema ou um registro são ações permanentes que não podem ser desfeitas.
## Excluir um esquema
Você pode querer excluir um esquema quando ele não for mais usado dentro de um registro usando o Console de gerenciamento da AWS ou a API [Ação DeleteSchema (Python: delete\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteSchema).
Excluir um ou mais esquemas é uma ação permanente que não pode ser desfeita. Certifique-se de que o esquema ou esquemas não são mais necessários.
Para excluir um esquema do registro, chame a API [Ação DeleteSchema (Python: delete\$1schema)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteSchema), especificando a estrutura `SchemaId` para identificar o esquema.
Por exemplo:
```
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 GlueConsole do**
Para excluir um esquema com o console do AWS Glue:
1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema registries** (Registros de esquemas).
1. Escolha o registro que contém o esquema na lista de registros.
1. Escolha um ou mais esquemas na lista, marcando as caixas.
1. No menu **Actions** (Ações), escolha **Delete schema** (Excluir esquema).
1. Insira o texto **Delete** no campo para confirmar a exclusão.
1. Selecione a opção **Excluir**.
Os esquemas especificados são excluídos do registro.
## Excluir uma versão de esquema
À medida que os esquemas se acumulam no registro, você pode querer excluir versões de esquema indesejadas usando o Console de gerenciamento da AWS ou a API [Ação DeleteSchemaVersions (Python: delete\$1schema\$1versions)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteSchemaVersions). Excluir uma ou mais versões de esquema é uma ação permanente que não pode ser desfeita. Certifique-se de que as versões de esquema não são mais necessárias.
Ao excluir versões de esquema, observe as seguintes restrições:
+ Você não pode excluir uma versão marcada como ponto de verificação.
+ O intervalo de versões contíguas não pode ser superior a 25.
+ A versão mais recente do esquema não deve estar em estado pendente.
Especifique a estrutura `SchemaId` para identificar o esquema e especifique `Versions` como um intervalo de versões a serem excluídas. Para obter mais informações sobre como especificar uma versão ou intervalo de versões, consulte [Ação DeleteRegistry (Python: delete\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteRegistry). As versões de esquema especificadas são excluídas do registro.
Chamar a API [Ação ListSchemaVersions (Python: list\$1schema\$1versions)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-ListSchemaVersions) após essa chamada listará o status das versões excluídas.
Por exemplo:
```
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. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema registries** (Registros de esquemas).
1. Escolha o registro que contém o esquema na lista de registros.
1. Escolha um ou mais esquemas na lista, marcando as caixas.
1. No menu **Actions** (Ações), escolha **Delete schema** (Excluir esquema).
1. Insira o texto **Delete** no campo para confirmar a exclusão.
1. Escolha **Excluir**.
As versões de esquema especificadas são excluídas do registro.
# Excluir um registro
Você pode querer excluir um registro quando os esquemas que ele contém não devem mais ser organizados nele. Você precisará reatribuir esses esquemas a outro registro.
Excluir um ou mais registros é uma ação permanente que não pode ser desfeita. Certifique-se de que o registro ou registros não são mais necessários.
O registro padrão pode ser excluído usando a AWS CLI.
**AWS GlueAPI**
Para excluir todo o registro, incluindo o esquema e todas as suas versões, chame a API [Ação DeleteRegistry (Python: delete\$1registry)](aws-glue-api-schema-registry-api.md#aws-glue-api-schema-registry-api-DeleteRegistry). Especifique uma estrutura `RegistryId` para identificar o registro.
Por exemplo:
```
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"
```
Para obter o status da operação de exclusão, é possível chamar a API `GetRegistry` após a chamada assíncrona.
**AWS GlueConsole do**
Para excluir um registro do console do AWS Glue:
1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Glue em [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue\).
1. No painel de navegação, em **Data catalog** (Catálogo de dados), escolha **Schema registries** (Registros de esquemas).
1. Escolha um registro na lista, marcando uma caixa.
1. No menu **Action** (Ação), escolha **Delete registry** (Excluir registro).
1. Insira o texto **Delete** no campo para confirmar a exclusão.
1. Selecione a opção **Excluir**.
Os registros que você selecionou são excluídos do AWS Glue.
## Exemplos do IAM para serializadores
**nota**
AWSAs políticas gerenciadas pela concedem as permissões necessárias para casos de uso comuns. Para obter informações sobre como usar políticas gerenciadas para gerenciar o registro do esquema, consulte [AWS Políticas gerenciadas pela (predefinidas) para o AWS Glue](security-iam-awsmanpol.md#access-policy-examples-aws-managed).
Para serializadores, você deve criar uma política mínima semelhante à abaixo, para lhe dar a capacidade de encontrar o `schemaVersionId` para uma determinada definição de esquema. Observe que você deve ter permissões de leitura no registro para ler os esquemas no registro. Você pode limitar os registros que podem ser lidos usando a cláusula `Resource`.
Exemplo de código 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"
]
}
```
Além disso, você também pode permitir que os produtores criem novos esquemas e versões ao incluir os seguintes métodos extras. Observe que você deve ser capaz de inspecionar o registro para adicionar/remover/evoluir os esquemas dentro dele. Você pode limitar os registros que podem ser inspecionados usando a cláusula `Resource`.
Exemplo de código 14:
```
{
"Sid" : "RegisterSchemaWithMetadata",
"Effect" : "Allow",
"Action" :
[
"glue:GetSchemaByDefinition",
"glue:CreateSchema",
"glue:RegisterSchemaVersion",
"glue:PutSchemaVersionMetadata",
],
"Resource" : ["arn:aws:glue:aws-region:123456789012:registry/registryname-1",
"arn:aws:glue:aws-region:123456789012:schema/registryname-1/schemaname-1",
"arn:aws:glue:aws-region:123456789012:schema/registryname-1/schemaname-2"
]
}
```
## Exemplos do IAM para desserializadores
Para desserializadores (lado do consumidor), você deve criar uma política semelhante à abaixo para permitir que o desserializador busque o esquema do registro de esquemas para desserialização. Observe que você deve ser capaz de inspecionar o registro a fim de buscar os esquemas dentro dele.
Exemplo de código 15:
```
{
"Sid" : "GetSchemaVersion",
"Effect" : "Allow",
"Action" :
[
"glue:GetSchemaVersion"
],
"Resource" : ["*"]
}
```
## Conectividade privada usando AWS PrivateLink
Você pode usar o AWS PrivateLink para conectar a VPC do produtor de dados ao AWS Glue definindo um endpoint da VPC de interface para o AWS Glue. Quando você usa um endpoint da VPC de interface, a comunicação entre sua VPC e o AWS Glue é realizada inteiramente dentro da rede da AWS. Para obter mais informações, consulte [Usar o AWS Glue com endpoints da VPC](https://docs.aws.amazon.com/glue/latest/dg/vpc-endpoint.html).
# Acessar métricas do Amazon CloudWatch
As métricas do Amazon CloudWatch estão disponíveis como parte do nível gratuito do CloudWatch. Também é possível visualizá-las no console do CloudWatch. As métricas de nível de API incluem CreateSchema (sucesso e latência), GetSchemaByDefinition (sucesso e latência), GetSchemaVersion (sucesso e latência), RegisterSchemaVersion (sucesso e latência) e PutSchemaVersionMetadata (sucesso e latência). As métricas de nível de recurso incluem Registry.ThrottledByLimit, SchemaVersion.ThrottledByLimit e SchemaVersion.Size.
# Exemplo de modelo do CloudFormation para o registro de esquemas
Veja a seguir um modelo de exemplo para criar recursos do registro de esquemas no CloudFormation. Para criar essa pilha em sua conta, copie o modelo acima em um arquivo `SampleTemplate.yaml` e execute o seguinte comando:
```
aws cloudformation create-stack --stack-name ABCSchemaRegistryStack --template-body "'cat SampleTemplate.yaml'"
```
Este exemplo usa `AWS::Glue::Registry` para criar um registro, `AWS::Glue::Schema` para criar um esquema, `AWS::Glue::SchemaVersion` para criar uma versão de esquema e `AWS::Glue::SchemaVersionMetadata` para preencher os metadados da versão do esquema.
```
Description: "A sample CloudFormation template for creating Schema Registry resources."
Resources:
ABCRegistry:
Type: "AWS::Glue::Registry"
Properties:
Name: "ABCSchemaRegistry"
Description: "ABC Corp. Schema Registry"
Tags:
Project: "Foo"
ABCSchema:
Type: "AWS::Glue::Schema"
Properties:
Registry:
Arn: !Ref ABCRegistry
Name: "TestSchema"
Compatibility: "NONE"
DataFormat: "AVRO"
SchemaDefinition: >
{"namespace":"foo.avro","type":"record","name":"user","fields":[{"name":"name","type":"string"},{"name":"favorite_number","type":"int"}]}
Tags:
Project: "Foo"
SecondSchemaVersion:
Type: "AWS::Glue::SchemaVersion"
Properties:
Schema:
SchemaArn: !Ref ABCSchema
SchemaDefinition: >
{"namespace":"foo.avro","type":"record","name":"user","fields":[{"name":"status","type":"string", "default":"ON"}, {"name":"name","type":"string"},{"name":"favorite_number","type":"int"}]}
FirstSchemaVersionMetadata:
Type: "AWS::Glue::SchemaVersionMetadata"
Properties:
SchemaVersionId: !GetAtt ABCSchema.InitialSchemaVersionId
Key: "Application"
Value: "Kinesis"
SecondSchemaVersionMetadata:
Type: "AWS::Glue::SchemaVersionMetadata"
Properties:
SchemaVersionId: !Ref SecondSchemaVersion
Key: "Application"
Value: "Kinesis"
```
# Integração com o registro de esquemas do AWS Glue
Estas seções descrevem integrações com o registro de esquemas do AWS Glue. Os exemplos nesta seção mostram um esquema com formato de dados AVRO. Para obter mais exemplos, incluindo esquemas com formato de dados JSON, consulte os testes de integração e as informações no arquivo ReadMe no [repositório de código aberto do registro de esquemas do AWS Glue](https://github.com/awslabs/aws-glue-schema-registry).
**Topics**
+ [Caso de uso: conectar registro de esquemas ao Amazon MSK ou Apache Kafka](#schema-registry-integrations-amazon-msk)
+ [Caso de uso: integração do Amazon Kinesis Data Streams ao registro de esquemas do AWS Glue](#schema-registry-integrations-kds)
+ [Caso de uso: Amazon Managed Service for Apache Flink](#schema-registry-integrations-kinesis-data-analytics-apache-flink)
+ [Caso de uso: integração com o AWS Lambda](#schema-registry-integrations-aws-lambda)
+ [Caso de uso: AWS Glue Data Catalog](#schema-registry-integrations-aws-glue-data-catalog)
+ [Caso de uso: transmissão no AWS Glue](#schema-registry-integrations-aws-glue-streaming)
+ [Caso de uso: Apache Kafka Streams](#schema-registry-integrations-apache-kafka-streams)
## Caso de uso: conectar registro de esquemas ao Amazon MSK ou Apache Kafka
Vamos supor que você está gravando dados em um tópico do Apache Kafka. Você pode seguir estas etapas para começar.
1. Crie um cluster do Amazon Managed Streaming for Apache Kafka (Amazon MSK) ou do Apache Kafka com pelo menos um tópico. Se estiver criando um cluster do Amazon MSK, você pode usar o Console de gerenciamento da AWS. Para obter mais informações: [Conceitos básicos do uso do Amazon MSK](https://docs.aws.amazon.com/msk/latest/developerguide/getting-started.html) no *Guia do desenvolvedor do Amazon Managed Streaming for Apache Kafka*.
1. Siga o passo [Instalar as bibliotecas SerDe](schema-registry-gs-serde.md) acima.
1. Para criar registros de esquemas, esquemas ou versões de esquema, siga as instruções na seção [Conceitos básicos do registro de esquemas](schema-registry-gs.md) deste documento.
1. Inicie seus produtores e consumidores para usar o registro de esquemas para gravar e ler registros de/para o tópico do Amazon MSK ou Apache Kafka. Um exemplo de código de produtor e consumidor pode ser encontrado no [arquivo ReadMe](https://github.com/awslabs/aws-glue-schema-registry/blob/master/README.md) das bibliotecas Serde. A biblioteca do registro de esquemas no produtor serializará automaticamente o registro e decorará o registro com um ID de versão do esquema.
1. Se o esquema desse registro tiver sido inserido, ou se o registro automático estiver ativado, o esquema será registrado no registro do esquemas.
1. O consumidor lendo do tópico do Amazon MSK ou Apache Kafka, usando a biblioteca do registro de esquemas do AWS Glue, pesquisará automaticamente o esquema no registro do esquemas.
## Caso de uso: integração do Amazon Kinesis Data Streams ao registro de esquemas do AWS Glue
Essa integração requer que você tenha um fluxo de dados existente do Amazon Kinesis. Para obter mais informações, consulte [Conceitos básicos do Amazon Kinesis Data Streams](https://docs.aws.amazon.com/streams/latest/dev/getting-started.html) no *Guia do desenvolvedor do Amazon Kinesis Data Streams*.
Há duas maneiras de interagir com os dados em um fluxo de dados do Kinesis.
+ Por meio das bibliotecas do Kinesis Producer Library (KPL) e Kinesis Client Library (KCL) em Java. Suporte a várias linguagens não é fornecido.
+ Por maio das APIs `PutRecords`, `PutRecord` e `GetRecords` do Kinesis Data Streams disponíveis no AWS SDK para Java.
Se você usa atualmente as bibliotecas KPL/KCL, recomendamos continuar usando esse método. Há versões atualizadas da KCL e KPL com o registro de esquemas integrado, como mostrado nos exemplos. Caso contrário, você pode usar o código de exemplo para utilizar o registro do esquemas do AWS Glue se estiver usando as APIs do KDS diretamente.
A integração do registro de esquemas só está disponível com a KPL v0.14.2 ou posterior e com a KCL v2.3 ou posterior. A integração do registro de esquemas com JSON só está disponível com a KPL v0.14.8 ou posterior e com a KCL v2.3.6 ou posterior.
### Interagir com dados usando o Kinesis SDK V2
Esta seção descreve a interação com o Kinesis usando o Kinesis SDK V2
```
// Example JSON Record, you can construct a AVRO record also
private static final JsonDataWithSchema record = JsonDataWithSchema.builder(schemaString, payloadString);
private static final DataFormat dataFormat = DataFormat.JSON;
//Configurations for Schema Registry
GlueSchemaRegistryConfiguration gsrConfig = new GlueSchemaRegistryConfiguration("us-east-1");
GlueSchemaRegistrySerializer glueSchemaRegistrySerializer =
new GlueSchemaRegistrySerializerImpl(awsCredentialsProvider, gsrConfig);
GlueSchemaRegistryDataFormatSerializer dataFormatSerializer =
new GlueSchemaRegistrySerializerFactory().getInstance(dataFormat, gsrConfig);
Schema gsrSchema =
new Schema(dataFormatSerializer.getSchemaDefinition(record), dataFormat.name(), "MySchema");
byte[] serializedBytes = dataFormatSerializer.serialize(record);
byte[] gsrEncodedBytes = glueSchemaRegistrySerializer.encode(streamName, gsrSchema, serializedBytes);
PutRecordRequest putRecordRequest = PutRecordRequest.builder()
.streamName(streamName)
.partitionKey("partitionKey")
.data(SdkBytes.fromByteArray(gsrEncodedBytes))
.build();
shardId = kinesisClient.putRecord(putRecordRequest)
.get()
.shardId();
GlueSchemaRegistryDeserializer glueSchemaRegistryDeserializer = new GlueSchemaRegistryDeserializerImpl(awsCredentialsProvider, gsrConfig);
GlueSchemaRegistryDataFormatDeserializer gsrDataFormatDeserializer =
glueSchemaRegistryDeserializerFactory.getInstance(dataFormat, gsrConfig);
GetShardIteratorRequest getShardIteratorRequest = GetShardIteratorRequest.builder()
.streamName(streamName)
.shardId(shardId)
.shardIteratorType(ShardIteratorType.TRIM_HORIZON)
.build();
String shardIterator = kinesisClient.getShardIterator(getShardIteratorRequest)
.get()
.shardIterator();
GetRecordsRequest getRecordRequest = GetRecordsRequest.builder()
.shardIterator(shardIterator)
.build();
GetRecordsResponse recordsResponse = kinesisClient.getRecords(getRecordRequest)
.get();
List