Este documento aborda os princípios básicos da recuperação de dados e como ordenar e filtrar dados do Firebase.
Antes de você começar
Certifique-se de ter configurado seu aplicativo e de poder acessar o banco de dados conforme abordado no guia Get Started .
Recuperando Dados
Os dados do Firebase são recuperados por uma chamada única para GetValue() ou anexando a um ValueListener em uma referência FirebaseDatabase . O ouvinte de valor é chamado uma vez para o estado inicial dos dados e novamente sempre que os dados mudam.
Obtenha uma referência de banco de dados
Para gravar dados no banco de dados, você precisa de uma instância de DatabaseReference :
// Get the root reference location of the database.
firebase::database::DatabaseReference dbref = database->GetReference();
Leia os dados uma vez
Você pode usar o método GetValue() para ler um instantâneo estático do conteúdo em um determinado caminho uma vez. O resultado da tarefa conterá um instantâneo contendo todos os dados naquele local, incluindo dados filho. Se não houver dados, o instantâneo retornado será null .
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").GetValue();
Nesse momento a solicitação foi feita, mas temos que esperar a conclusão do Future antes de podermos ler o valor. Como os jogos normalmente são executados em loop e são menos orientados por retorno de chamada do que outros aplicativos, você normalmente fará uma pesquisa para conclusão.
// In the game loop that polls for the result...
if (result.status() != firebase::kFutureStatusPending) {
if (result.status() != firebase::kFutureStatusComplete) {
LogMessage("ERROR: GetValue() returned an invalid result.");
// Handle the error...
} else if (result.error() != firebase::database::kErrorNone) {
LogMessage("ERROR: GetValue() returned error %d: %s", result.error(),
result.error_message());
// Handle the error...
} else {
firebase::database::DataSnapshot snapshot = result.result();
// Do something with the snapshot...
}
}
Isso mostra algumas verificações básicas de erros. Consulte a referência firebase::Future para obter mais informações sobre verificação de erros e maneiras de determinar quando o resultado estará pronto.
Ouça eventos
Você pode adicionar ouvintes para assinar alterações nos dados:
Classe base ValueListener
| Ligar de volta | Uso típico |
|---|---|
OnValueChanged | Leia e ouça alterações em todo o conteúdo de um caminho. |
Classe base OnChildListener
OnChildAdded | Recuperar listas de itens ou ouvir adições a uma lista de itens. Uso sugerido com OnChildChanged e OnChildRemoved para monitorar alterações em listas. |
OnChildChanged | Ouça as alterações nos itens de uma lista. Use com OnChildAdded e OnChildRemoved para monitorar alterações nas listas. |
OnChildRemoved | Ouça os itens sendo removidos de uma lista. Use com OnChildAdded e OnChildChanged para monitorar alterações nas listas. |
OnChildMoved | Ouça as alterações na ordem dos itens em uma lista ordenada. Os retornos de chamada OnChildMoved sempre seguem os retornos de chamada OnChildChanged devido à alteração da ordem do item (com base no seu método de pedido atual). |
Classe ValueListener
Você pode usar os retornos de chamada OnValueChanged para assinar alterações no conteúdo em um determinado caminho. Esse retorno de chamada é acionado uma vez quando o ouvinte é anexado e novamente sempre que os dados, incluindo filhos, são alterados. O retorno de chamada recebe um instantâneo contendo todos os dados naquele local, incluindo dados filho. Se não houver dados, o instantâneo retornado será null .
O exemplo a seguir demonstra um jogo recuperando as pontuações de um placar do banco de dados:
class LeadersValueListener : public firebase::database::ValueListener {
public:
void OnValueChanged(
const firebase::database::DataSnapshot& snapshot) override {
// Do something with the data in snapshot...
}
void OnCancelled(const firebase::database::Error& error_code,
const char* error_message) override {
LogMessage("ERROR: LeadersValueListener canceled: %d: %s", error_code,
error_message);
}
};
// Elsewhere in the code...
LeadersValueListener* listener = new LeadersValueListener();
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("Leaders").AddValueListener(listener);
O resultado Future<DataSnapshot> contém os dados no local especificado no banco de dados no momento do evento. Chamar value() em um snapshot retorna uma Variant que representa os dados.
Neste exemplo, o método OnCancelled também é substituído para verificar se a leitura foi cancelada. Por exemplo, uma leitura poderá ser cancelada se o cliente não tiver permissão para ler em um local de banco de dados do Firebase. O database::Error indicará por que a falha ocorreu.
Classe ChildListener
Os eventos filho são acionados em resposta a operações específicas que acontecem aos filhos de um nó a partir de uma operação, como um novo filho adicionado por meio do método PushChild() ou um filho sendo atualizado por meio do método UpdateChildren() . Cada um deles juntos pode ser útil para ouvir alterações em um nó específico em um banco de dados. Por exemplo, um jogo pode usar esses métodos juntos para monitorar a atividade nos comentários de uma sessão de jogo, conforme mostrado abaixo:
class SessionCommentsChildListener : public firebase::database::ChildListener {
public:
void OnChildAdded(const firebase::database::DataSnapshot& snapshot,
const char* previous_sibling) override {
// Do something with the data in snapshot ...
}
void OnChildChanged(const firebase::database::DataSnapshot& snapshot,
const char* previous_sibling) override {
// Do something with the data in snapshot ...
}
void OnChildRemoved(
const firebase::database::DataSnapshot& snapshot) override {
// Do something with the data in snapshot ...
}
void OnChildMoved(const firebase::database::DataSnapshot& snapshot,
const char* previous_sibling) override {
// Do something with the data in snapshot ...
}
void OnCancelled(const firebase::database::Error& error_code,
const char* error_message) override {
LogMessage("ERROR: SessionCommentsChildListener canceled: %d: %s",
error_code, error_message);
}
};
// elsewhere ....
SessionCommentsChildListener* listener = new SessionCommentsChildListener();
firebase::Future<firebase::database::DataSnapshot> result =
dbRef.GetReference("GameSessionComments").AddChildListener(listener);
O retorno de chamada OnChildAdded normalmente é usado para recuperar uma lista de itens em um banco de dados Firebase. O retorno de chamada OnChildAdded é chamado uma vez para cada filho existente e novamente sempre que um novo filho é adicionado ao caminho especificado. O ouvinte recebe um instantâneo contendo os dados do novo filho.
O retorno de chamada OnChildChanged é chamado sempre que um nó filho é modificado. Isto inclui quaisquer modificações nos descendentes do nó filho. Geralmente é usado em conjunto com as chamadas OnChildAdded e OnChildRemoved para responder a alterações em uma lista de itens. O instantâneo passado ao ouvinte contém os dados atualizados do filho.
O retorno de chamada OnChildRemoved é acionado quando um filho imediato é removido. Geralmente é usado em conjunto com os retornos de chamada OnChildAdded e OnChildChanged . O instantâneo passado para o retorno de chamada contém os dados do filho removido.
O retorno de chamada OnChildMoved é acionado sempre que a chamada OnChildChanged é gerada por uma atualização que causa a reordenação do filho. É usado com dados ordenados com OrderByChild ou OrderByValue .
Classificando e filtrando dados
Você pode usar a classe Realtime Database Query para recuperar dados classificados por chave, por valor ou por valor de um filho. Você também pode filtrar o resultado classificado para um número específico de resultados ou um intervalo de chaves ou valores.
Classificar dados
Para recuperar dados classificados, comece especificando um dos métodos ordenados por para determinar como os resultados são ordenados:
| Método | Uso |
|---|---|
OrderByChild() | Ordene os resultados pelo valor de uma chave filha especificada. | OrderByKey() | Ordene os resultados por chaves filhas. |
OrderByValue() | Ordene os resultados por valores filhos. |
Você só pode usar um método de ordem por vez. Chamar um método ordenado várias vezes na mesma consulta gera um erro.
O exemplo a seguir demonstra como você pode assinar um placar de pontuação ordenado por pontuação.
firebase::database::Query query =
dbRef.GetReference("Leaders").OrderByChild("score");
// To get the resulting DataSnapshot either use query.GetValue() and poll the
// future, or use query.AddValueListener() and register to handle the
// OnValueChanged callback.
Isso define um firebase::Query que quando combinado com um ValueListener sincroniza o cliente com o placar no banco de dados, ordenado pela pontuação de cada entrada. Você pode ler mais sobre como estruturar seus dados de forma eficiente em Estruture seu banco de dados .
A chamada ao método OrderByChild() especifica a chave filha pela qual ordenar os resultados. Neste caso, os resultados são ordenados pelo valor da "score" em cada filho. Para obter mais informações sobre como outros tipos de dados são ordenados, consulte Como os dados de consulta são ordenados .
Filtrando dados
Para filtrar dados, você pode combinar qualquer um dos métodos de limite ou intervalo com um método ordenado por ao construir uma consulta.
| Método | Uso |
|---|---|
LimitToFirst() | Define o número máximo de itens a serem retornados do início da lista ordenada de resultados. |
LimitToLast() | Define o número máximo de itens a serem retornados do final da lista ordenada de resultados. |
StartAt() | Retorna itens maiores ou iguais à chave ou valor especificado dependendo do método de ordenação escolhido. |
EndAt() | Retorna itens menores ou iguais à chave ou valor especificado, dependendo do método de ordenação escolhido. |
EqualTo() | Retorna itens iguais à chave ou valor especificado dependendo do método de ordenação escolhido. |
Ao contrário dos métodos ordenados, você pode combinar várias funções de limite ou intervalo. Por exemplo, você pode combinar os métodos StartAt() e EndAt() para limitar os resultados a um intervalo especificado de valores.
Mesmo quando há apenas uma correspondência para a consulta, o instantâneo ainda é uma lista; ele contém apenas um único item.
Limite o número de resultados
Você pode usar os métodos LimitToFirst() e LimitToLast() para definir um número máximo de filhos a serem sincronizados para um determinado retorno de chamada. Por exemplo, se você usar LimitToFirst() para definir um limite de 100, inicialmente receberá apenas até 100 retornos de chamada OnChildAdded . Se você tiver menos de 100 itens armazenados no banco de dados do Firebase, um retorno de chamada OnChildAdded será acionado para cada item.
À medida que os itens mudam, você recebe retornos de chamada OnChildAdded para itens que entram na consulta e retornos de chamada OnChildRemoved para itens que saem dela, de modo que o número total permaneça em 100.
Por exemplo, o código abaixo retorna a pontuação máxima de um placar:
firebase::database::Query query =
dbRef.GetReference("Leaders").OrderByChild("score").LimitToLast(1);
// To get the resulting DataSnapshot either use query.GetValue() and poll the
// future, or use query.AddValueListener() and register to handle the
// OnValueChanged callback.
Filtrar por chave ou valor
Você pode usar StartAt() , EndAt() e EqualTo() para escolher pontos iniciais, finais e de equivalência arbitrários para consultas. Isso pode ser útil para paginar dados ou encontrar itens com filhos que tenham um valor específico.
Como os dados da consulta são ordenados
Esta seção explica como os dados são classificados por cada um dos métodos ordenados na classe Query .
OrderByChild
Ao usar OrderByChild() , os dados que contêm a chave filha especificada são ordenados da seguinte forma:
- Os filhos com um valor
nullpara a chave filha especificada vêm primeiro. - Os filhos com um valor
falsepara a chave filha especificada vêm em seguida. Se vários filhos tiverem um valorfalse, eles serão classificados lexicograficamente por chave. - Os filhos com um valor
truepara a chave filha especificada vêm em seguida. Se vários filhos tiverem um valortrue, eles serão classificados lexicograficamente por chave. - Os filhos com valor numérico vêm em seguida, classificados em ordem crescente. Se vários filhos tiverem o mesmo valor numérico para o nó filho especificado, eles serão classificados por chave.
- As strings vêm depois dos números e são classificadas lexicograficamente em ordem crescente. Se vários filhos tiverem o mesmo valor para o nó filho especificado, eles serão ordenados lexicograficamente por chave.
- Os objetos vêm por último e são classificados lexicograficamente por chave em ordem crescente.
OrderByKey
Ao usar OrderByKey() para classificar seus dados, os dados são retornados em ordem crescente por chave.
- Os filhos com uma chave que pode ser analisada como um número inteiro de 32 bits vêm primeiro, classificados em ordem crescente.
- Os filhos com um valor de string como chave vêm em seguida, classificados lexicograficamente em ordem crescente.
OrderByValue
Ao usar OrderByValue() , os filhos são ordenados por seu valor. Os critérios de ordenação são os mesmos de OrderByChild() , exceto que o valor do nó é usado em vez do valor de uma chave filha especificada.