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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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âmetro	Descrição	Valor padrão	Tipo 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:

Expressão condicional exemplo 1

Expressão condicional exemplo 2

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:

Expressão condicional exemplo 3

Expressão condicional exemplo 4 - detalhe Placeholder

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:

Expressão condicional exemplo 5 - Sort Key Expression

Expressão condicional exemplo 6 - Filter Expression

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:

Expressão condicional exemplo 7 - Exclusive Start Key