BatchGetItem

Importante

Esta seção refere-se à versão de API 2011-12-05, que está obsoleta e não deve ser usada para novos aplicativos.

Para obter a documentação da API de baixo nível atual, consulte a Referência da API do Amazon DynamoDB.

Descrição

A operação BatchGetItem retorna os atributos para vários itens de várias tabelas usando suas chaves primárias. O número máximo de itens que podem ser recuperados para uma única operação é 100. Além disso, o número de itens recuperados é restrito por um limite de tamanho de 1 MB. Se o limite de tamanho da resposta for excedido ou se um resultado parcial for retornado porque o throughput provisionado da tabela foi excedida, ou devido a uma falha de processamento interno, o DynamoDB retornará um valor de UnprocessedKeys para que você possa tentar novamente a operação começando com o próximo item a ser obtido. O DynamoDB ajusta automaticamente o número de itens retornados por página para impor esse limite. Por exemplo, mesmo que você solicite o retorno de 100 itens, mas cada item tem um tamanho de 50 KB, o sistema retornará 20 itens e um valor de UnprocessedKeys apropriado para que você possa obter a próxima página de resultados. Se você desejar, o aplicativo pode incluir sua própria lógica para reunir as páginas de resultados em um único conjunto.

Se nenhum item pôde ser processado devido a um throughput provisionado insuficiente em cada uma das tabelas envolvidas na solicitação, o DynamoDB retornará um erro ProvisionedThroughputExceededException.

nota

Por padrão, o BatchGetItem realiza leituras finais consistentes em cada tabela da solicitação. Você pode definir o parâmetro ConsistentRead como true para cada tabela se quiser leituras consistentes.

BatchGetItem busca itens em paralelo para minimizar latências de resposta.

Ao projetar sua aplicação, tenha em mente que o DynamoDB não garante como os atributos são ordenados na resposta retornada. Inclua os valores de chaves primárias no AttributesToGet dos itens na sua solicitação para ajudar a analisar a resposta por item.

Se os itens solicitados não existirem, nada será retornado na resposta para esses itens. Solicitações de itens inexistentes consomem as unidades mínimas de capacidade de leitura de acordo com o tipo de leitura. Para mais informações, consulte Tamanhos e formatos de item do DynamoDB.

Solicitações

Sintaxe

// This header is abbreviated. For a sample of a complete header, see API de baixo nível do DynamoDB.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.BatchGetItem 
content-type: application/x-amz-json-1.0 

{"RequestItems":
    {"Table1": 
        {"Keys": 
            [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}},
            {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}},
            {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}],
        "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
    "Table2": 
        {"Keys": 
            [{"HashKeyElement": {"S":"KeyValue4"}}, 
            {"HashKeyElement": {"S":"KeyValue5"}}],
        "AttributesToGet": ["AttributeName4", "AttributeName5", "AttributeName6"]
        }
    }
}

Name (Nome)	Descrição	Obrigatório
RequestItems	Um contêiner do nome da tabela e de itens correspondentes a serem obtidos por chave primária. Ao solicitar itens, cada nome de tabela pode ser invocado apenas uma vez por operação. Tipo: string Padrão: nenhum	Sim
Table	O nome da tabela que contém os itens a serem obtidos. A entrada é simplesmente uma string especificando uma tabela existente, sem rótulo. Tipo: string Padrão: nenhum	Sim
Table:Keys	Os valores de chave primária que definem os itens na tabela especificada. Para obter mais informações sobre chaves primárias, consulte Chave primária. Tipo: Chaves	Sim
Table:AttributesToGet	Matriz de nomes de atributos dentro da tabela especificada. Se os nomes de atributos não forem especificados, todos os atributos serão retornados. Se alguns atributos não forem encontrados, eles não serão exibidos no resultado. Tipo: matriz	Não
Table:ConsistentRead	Se definido como true, uma leitura consistente será emitida; caso contrário, uma leitura eventualmente consistente será usada. Type: booliano	Não

Respostas

Sintaxe

HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0 
content-length: 855

{"Responses":
    {"Table1":
        {"Items":
        [{"AttributeName1": {"S":"AttributeValue"},
        "AttributeName2": {"N":"AttributeValue"},
        "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]}
        },
        {"AttributeName1": {"S": "AttributeValue"},
        "AttributeName2": {"S": "AttributeValue"},
        "AttributeName3": {"NS": ["AttributeValue", "AttributeValue", "AttributeValue"]}
        }],
    "ConsumedCapacityUnits":1},
    "Table2": 
        {"Items":
        [{"AttributeName1": {"S":"AttributeValue"},
        "AttributeName2": {"N":"AttributeValue"},
        "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]}
        },
        {"AttributeName1": {"S": "AttributeValue"},
        "AttributeName2": {"S": "AttributeValue"},
        "AttributeName3": {"NS": ["AttributeValue", "AttributeValue","AttributeValue"]}
        }],
    "ConsumedCapacityUnits":1}
    },
    "UnprocessedKeys":
        {"Table3": 
        {"Keys": 
            [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}},
            {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}},
            {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}],
        "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}
        }
}

Name (Nome)	Descrição
Responses	Nomes de tabelas e os respectivos atributos de itens das tabelas. Tipo: mapa
Table	O nome da tabela que contém os itens. A entrada é simplesmente uma string especificando a tabela, sem rótulo. Tipo: string
Items	Contêiner para nomes de atributos e valores que atendem aos parâmetros de operação. Tipo: mapa de nomes de atributo e seus tipos de dados e valores.
ConsumedCapacityUnits	O número de unidades de capacidade de leitura consumidas, para cada tabela. Esse valor mostra o número utilizado no throughput provisionado. As solicitações de itens não existentes consomem o mínimo de unidades de capacidade de leitura, dependendo do tipo de leitura. Para obter mais informações, consulte Gerenciar configurações em tabelas com capacidade provisionada do DynamoDB. Tipo: número
UnprocessedKeys	Contém uma matriz de tabelas e suas respectivas chaves que não foram processadas com a resposta atual, possivelmente devido a um limite atingido no tamanho da resposta. O valor UnprocessedKeys está no mesmo formato que um parâmetro RequestItems (portanto, ele pode ser fornecido diretamente a uma operação BatchGetItem posterior). Para obter mais informações, consulte o parâmetro RequestItems acima. Tipo: matriz
UnprocessedKeys: Table: Keys	Os valores de atributos de chave primária que definem os itens e os atributos associados a esses itens. Para obter mais informações sobre chaves primárias, consulte Chave primária. Tipo: matriz de pares de nome-valor de atributo.
UnprocessedKeys: Table: AttributesToGet	Nomes de atributos na tabela especificada. Se os nomes de atributos não forem especificados, todos os atributos serão retornados. Se alguns atributos não forem encontrados, eles não serão exibidos no resultado. Tipo: Matriz de nomes de atributos.
UnprocessedKeys: Table: ConsistentRead	Se definido como true, uma leitura consistente será usada para a tabela especificada; caso contrário, uma leitura eventualmente consistente será usada. Tipo: booleano.

Erros especiais

Erro	Descrição
ProvisionedThroughputExceededException	O throughput provisionado máximo permitido foi excedido.

Exemplos

Os exemplos a seguir mostram uma solicitação HTTP POST e uma resposta usando a operação BatchGetItem. Para obter exemplos sobre o uso do AWS SDK, consulte Trabalhar com itens e atributos.

Exemplo de solicitação

O exemplo a seguir solicita atributos de duas tabelas diferentes.

// This header is abbreviated. 
// For a sample of a complete header, see API de baixo nível do DynamoDB.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.BatchGetItem 
content-type: application/x-amz-json-1.0 
content-length: 409

{"RequestItems":
    {"comp1":
        {"Keys":
            [{"HashKeyElement":{"S":"Casey"},"RangeKeyElement":{"N":"1319509152"}},
            {"HashKeyElement":{"S":"Dave"},"RangeKeyElement":{"N":"1319509155"}},
            {"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"1319509158"}}],
        "AttributesToGet":["user","status"]},
    "comp2":
        {"Keys":
            [{"HashKeyElement":{"S":"Julie"}},{"HashKeyElement":{"S":"Mingus"}}],
        "AttributesToGet":["user","friends"]}
    }
}

Exemplo de resposta

O exemplo a seguir é a resposta.

HTTP/1.1 200 OK
x-amzn-RequestId: GTPQVRM4VJS792J1UFJTKUBVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0 
content-length: 373
Date: Fri, 02 Sep 2011 23:07:39 GMT

{"Responses":
    {"comp1":
        {"Items":
            [{"status":{"S":"online"},"user":{"S":"Casey"}},
            {"status":{"S":"working"},"user":{"S":"Riley"}},
            {"status":{"S":"running"},"user":{"S":"Dave"}}],
        "ConsumedCapacityUnits":1.5},
    "comp2":
        {"Items":
            [{"friends":{"SS":["Elisabeth", "Peter"]},"user":{"S":"Mingus"}},
            {"friends":{"SS":["Dave", "Peter"]},"user":{"S":"Julie"}}],
        "ConsumedCapacityUnits":1}
    },
    "UnprocessedKeys":{}
}