PT-BR
Digibee.comDigibee Academy

DynamoDB

Saiba mais sobre o conector DynamoDB e como utilizá-lo na Digibee Integration Platform.

O conector DynamoDB permite que pipelines realizem operações em tabelas DynamoDB na AWS. Atualmente, estão disponíveis as seguintes operações:

  • PutItem: cria ou substitui um item em uma tabela DynamoDB.

  • GetItem: busca atributos de um item existente em uma tabela DynamoDB pela chave primária.

  • UpdateItem: edita os atributos de um item existente ou adiciona um item novo a uma tabela DynamoDB.

  • DeleteItem: remove um único item em uma tabela pela chave primária.

  • Query: busca todos os itens com a mesma chave de partição (partition key) de uma tabela ou índice (secundário local ou secundário global).

  • Scan: busca todos os itens de uma tabela ou índice (secundário local ou secundário global). Uma expressão de filtro pode ser aplicada para limitar o número de itens retornados.

Parâmetros

Os parâmetros disponíveis estão divididos em quatro abas e podem variar de acordo com a operação selecionada. Parâmetros suportados por expressões Double Braces estão marcados com (DB).

Aba General

ParâmetroDescriçãoValor padrãoTipo de dado

Fail On Error

Se a opção estiver ativada, a execução do pipeline com um erro será interrompida. Do contrário, a execução do pipeline será mantida, mas o resultado mostrará um valor falso para a propriedade "success".

False

Booleano

Aba Authentication

ParâmetroDescriçãoValor padrãoTipo de dado

Account Type

Especifica o tipo de conta da conta principal usada para a conexão. Tipos suportados: AWS V4 e Basic.

Basic

String

Use Dynamic Account

Quando ativo, o conector usará a conta dinamicamente. Caso contrário, usará a conta de forma estática.

False

Booleano

Scoped

Quando ativo, a conta armazenada fica isolada de outros subprocessos. Nesse caso, os subprocessos veem sua própria versão dos dados da conta armazenada.

Este parâmetro fica disponível apenas se o parâmetro Use Dynamic Account estiver ativo.

False

Booleano

Account

A conta usada para conectar o conector à tabela alvo do DynamoDB.

Este parâmetro fica disponível apenas se o parâmetro Use Dynamic Account estiver inativo.

NULL

BASIC, AWS-V4

Account Name (DB)

O nome da conta dinâmica usada para conectar o conector à tabela alvo do DynamoDB. Esta conta deve ter sido previamente configurada em um conector Store Account no pipeline para que este processo tenha efeito.

Este parâmetro fica disponível apenas se o parâmetro Use Dynamic Account estiver ativo.

Vazio

String

AWS Region

A região da AWS onde a tabela alvo está disponível.

É usada apenas quando o tipo de conta está configurado como Basic.

us-east-1

String

Use Assume Role

Quando ativo, permite o uso de uma conta AWS Role a ser assumida pela Account.

Só pode ser usado se o tipo de conta estiver configurado como AWS V4.

False

Booleano

AWS Role Account

A conta usada para delegar permissões temporárias à Account por meio da operação Assume Role.

NULL

AWS-ROLE

AWS Role Account Name (DB)

O nome da conta dinâmica usada para delegar permissões temporárias à conta referenciada no campo Account Name por meio da operação Assume Role.

Este parâmetro fica disponível apenas se o parâmetro Use Dynamic Account estiver ativo.

Vazio

String

Aba Operation Settings

ParâmetroDescriçãoValor padrãoTipo de dado

Operation

Operação a ser realizada.

PutItem

String

Table Name

Nome da tabela na qual a operação será realizada.

NULL

String

Parâmetros da operação PutItem

ParâmetroDescriçãoValor padrãoTipo de dado

Upsert

Quando ativado, o parâmetro substitui completamente um item existente com a mesma chave primária. Do contrário, a operação irá falhar quando um item com a chave primária especificada já existir.

True

Booleano

Body (DB)

Objeto JSON a ser usado pela operação.

Arrays JSON e outras definições válidas de JSON não são permitidas.

{{ message.$ }}

JSON

Parâmetros da operação GetItem

ParâmetroDescriçãoValor padrãoTipo de dado

Partition Key Value (DB)

Valor da chave de partição (partition key) do item de destino. Este parâmetro é obrigatório.

NULL

String

Sort Key Value (DB)

Valor da chave de classificação (sort key) do item de destino. É necessária somente quando a tabela de destino usa uma chave primária composta (chave de partição + chave de classificação).

NULL

String

Attributes to Return (DB)

Lista de nomes de atributos separados por vírgula a serem retornados pela operação.

NULL

String

Consistent Read

Este parâmetro se sobrepõe ao comportamento padrão de consistência eventual do DynamoDB quando ativado.

False

Booleano

Parâmetros da operação UpdateItem

ParâmetroDescriçãoValor padrãoTipo de dado

Partition Key Value (DB)

Valor da chave de partição do item de destino. Este parâmetro é obrigatório.

NULL

String

Sort Key Value (DB)

Valor da chave de classificação do item de destino. É necessária somente quando a tabela de destino usa uma chave primária composta (chave de partição + chave de classificação).

NULL

String

Return Values

Lista de opções para obter os valores dos atributos, antes ou depois da operação de atualização ser realizada.

As opções são: ALL NEW (Retorna todos os valores como estão, após atualizar), ALL OLD (Todos os valores como estavam antes de atualizar), NONE (Nada é retornado), UPDATED NEW (Somente valores atualizados são retornados como estão após atualizar), e UPDATED OLD (Somente valores atualizados como estavam antes de atualizar).

NONE

String

Body (DB)

Objeto JSON a ser usado pela operação.

Arrays JSON e outras definições válidas de JSON não são permitidas.

{{ message.$ }}

JSON

Parâmetros da operação DeleteItem

ParâmetroDescriçãoValor padrãoTipo de dado

Partition Key Value (DB)

Valor da chave de partição do item de destino. Este parâmetro é obrigatório.

NULL

String

Sort Key Value (DB)

Valor da chave de classificação do item de destino. É necessária somente quando a tabela de destino usa uma chave primária composta (chave de partição + chave de classificação).

NULL

String

Parâmetros da operação Query

ParâmetroDescriçãoValor padrãoTipo de dado

Index Name

Nome do índice a ser usado nesta operação. O índice deve pertencer à tabela especificada no campo Table Name.

NULL

String

Partition Key Value (DB)

Valor da chave de partição do item de destino. Este valor irá se referir a um índice da chave de partição (Index Partition Key), se o campo Index Name estiver especificado. Este parâmetro é obrigatório.

NULL

String

Sort Key Expression (DB)

Uma expressão condicional a ser aplicada ao atributo da chave de classicação. A expressão irá se referir a um índice da chave de classificação (Index Sort Key), se o campo Index Name estiver especificado.

NULL

String

Attributes to Return (DB)

Lista de nomes de atributos a serem retornados pela operação.

NULL

String

Consistent Read

Este parâmetro se sobrepõe ao comportamento padrão de consistência eventual do DynamoDB quando ativado. Não pode ser usado quando a operação Query é usada contra um índice secundário global (GSI).

False

Booleano

Filter Expression (DB)

Uma string que contém condições que o DynamoDB aplica após a operação Query, mas antes dos dados serem retornados para você.

NULL

String

Exclusive Start Partition Key Value (DB)

A chave de partição do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.

NULL

String

Exclusive Start Sort Key Value (DB)

A chave de classiicação do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.

NULL

String

Exclusive Start Index Partition Key Value (DB)

A chave de partição do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.

NULL

String

Exclusive Start Index Sort Key Value (DB)

A chave de classificação do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.

NULL

String

Limit

O número máximo de itens a serem retornados pela operação. O valor mínimo permitido é 1 e o máximo é 1000.

1000

Inteiro

Automatic Pagination

Se ativo, este parâmetro irá buscar automaticamente todas as páginas quando o DynamoDB retornar respostas paginadas.

False

Booleano

Scan Forward

Se ativo, este parâmetro retorna o resultado em sua ordem original (baseado na chave de classificação). Do contrário, a ordem é invertida.

True

Booleano

Expression Attribute Values (DB)

Uma lista de valores de atributos usados nos campos de expressão condicional (Sort Key Expression e Filter Expression). Cada valor de atributo deve especificar o placeholder usado (Placeholder), o tipo de dado (Type) e o valor (Value) para substituir o placeholder.

Vazio

Lista de valores de atributos

Parâmetros da operação Scan

ParâmetroDescriçãoValor padrãoTipo de dado

Index Name

Nome do índice a ser usado nesta operação. O índice deve pertencer à tabela especificada no campo Table Name.

NULL

String

Attributes to Return (DB)

Lista de nomes de atributos a serem retornados pela operação.

NULL

String

Consistent Read

Este parâmetro se sobrepõe ao comportamento padrão de consistência eventual do DynamoDB quando ativado. Não pode ser usado quando a operação Scan é usada contra um índice secundário global (GSI).

False

Booleano

Filter Expression (DB)

Uma string que contém condições que o DynamoDB aplica após a operação Scan, mas antes dos dados serem retornados para você.

NULL

String

Exclusive Start Partition Key Value (DB)

A chave de partição do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.

NULL

String

Exclusive Start Sort Key Value (DB)

A chave de classiicação do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados.

NULL

String

Exclusive Start Index Partition Key Value (DB)

A chave de partição do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.

NULL

String

Exclusive Start Index Sort Key Value (DB)

A chave de classificação do índice do primeiro item que esta operação irá avaliar. Este atributo é obrigatório apenas quando estiver buscando resultados paginados de um índice.

NULL

String

Limit

O número máximo de itens a serem retornados pela operação. O valor mínimo permitido é 1 e o máximo é 1000.

1000

Inteiro

Automatic Pagination

Se ativo, este parâmetro irá buscar automaticamente todas as páginas quando o DynamoDB retornar respostas paginadas.

False

Booleano

Scan Forward

Se ativo, este parâmetro retorna o resultado em sua ordem original (baseado na chave de classificação). Do contrário, a ordem é invertida.

True

Booleano

Expression Attribute Values (DB)

Uma lista de valores de atributos usados nos campos de expressão condicional (Filter Expression). Cada valor de atributo deve especificar o placeholder usado (Placeholder), o tipo de dado (Type) e o valor (Value) para substituir o placeholder.

Vazio

Lista de valores de atributos

Saída

Todas as operações retornam:

  • Um atributo booleano "success" para indicar se a operação foi realizada com sucesso (true) ou se falhou (false).

  • Um atributo de contagem, indicando quantos itens foram afetados pela operação. Este parâmetro recebe o nome da operação no seguinte formato: operation's name + Count.

  • Um atributo "data" contendo um array de registros de itens retornados. Isto é restrito às operações que retornam algum resultado.

Exemplo GetItem

{
	"success": true,
	"getItemCount": 1,
	"data": [
		{
	"Age": 8,
	"Colors": [
		"White", 
		"Brown",
		"Black"
],
"Name": "Fido",
"Vaccinations": {
	"Rabies": [
		"2009-03-17",
		"2011-09-21",
		"2014-07-08"
	],
	"Distemper": "2015-10-13"
},
"Breed": "Beagle",
"AnimalType": "Dog"
}
	]
}

Query e Scan - detalhes adicionais

Expressões condicionais

Ao usar as operações Query e Scan, você pode usar expressões condicionais para filtrar os resultados retornados. As expressões condicionais podem ser definidas nos campos Sort Key Expression (disponível apenas na operação Query) e Filter Expression (disponível nas operações Query e Scan).

Estas expressões são similares às opções de filtro em uma query SQL, como pode ser visto nos exemplos a seguir:

Perceba que os valores reais a serem usados nas condições não podem ser colocados diretamente nas expressões. Como alternativa, um placeholder no formato "dois pontos + nome" deve ser usado, e o valor é então passado pelo campo Expression Attribute Values field. No exemplo acima, os seguintes valores de atributos teriam que ser especificados:

Observe que o valor do campo Placeholder deve corresponder exataente aos nomes usados nas expressões condicionais, incluíndo as vírgulas.

Double Braces em expressões condicionais

Ao usar expressões Double Braces dentro de expressões condicionais, não há necessidade de especificar os valores correspondentes pelo campo Expression Attribute Values. O mesmo exemplo acima poderia ter sido especificado desta forma:

Neste caso, o conector infere os tipos de dados e valores da mensagem de entrada JSON. Os placeholders são gerados automaticamente pelo conector usando números sequenciais. Nesta situação, seria esperada uma mensagem de entrada como no exemplo a seguir:

{
	"skMinValue": 8965,
	"skMaxValue": 9165,
	"createdAtBottom": "2024-03-25T16:11:22Z",
	"deletedVal": false
}

Leia a documentação da AWS para mais detalhes sobre expressões condicionais.

Resultados paginados

O DynamoDB pode paginar os resultados de uma operação Query ou Scan operation em duas situações:

  • O número de itens buscados é maior do que o número estabelecido no parâmetro Limit.

  • O tamanho total da resposta supera 1MB.

Em situações onde uma resposta paginada é retornada, um campo extra lastEvaluatedKey será adicionado à saída, contendo as chaves primárias do último item retornado. Estas chaves retornadas podem então ser usadas em operações subsequentes Query ou Scan ao aplicá-las nos campos Exclusive Start Key.

Na sequência, temos um exemplo de saída paginada:

{
	"success": true,
       	"data":[
		{...},
		{...},
		{...},
		...
	],
	"queryCount": 1000,
	"lastEvaluatedKey": {
		"partitionKeyName": 12,
		"sortKeyName" "abc",
		"indexPartitionKeyName": 123,
		"indexSortKeyName": "index-abc"
	}
}

Perceba que nesse caso, temos uma mapa entre os campos com nomes de chaves e seus respectivos valores. Os campos-chave de índice são omitidos se a operação não tiver o campo Index Name especificado.

Os campos Exclusive Start Key teriam que estar especificados conforme a imagem a seguir para a seguinte iteração de página:

AnteriorArangoDbPróximoMemcached

Atualizado