Atualizar arrays
Nesta página
- Visão geral
- Dados de amostra
- Adicionar um valor
- Adicionar vários valores
- Remove Values
- Primeiro valor
- Valor Última
- Todas as instâncias de um valor
- Todas as instâncias de vários valores
- Todos os valores que correspondem a uma condição
- Atualizar valores correspondentes
- Primeiro valor correspondente
- Todos os valores correspondentes
- All Values
- Documentação da API
Visão geral
Nesta página, você aprenderá a criar objetos UpdateDefinition
para campos de array. Um objeto UpdateDefinition
especifica o tipo de operação de atualização a ser executada, os campos a serem atualizados e o novo valor para cada campo, se aplicável.
O driver .NET/C# é compatível com os operadores e modificadores de atualização da array descritos no manual do MongoDB Server. Para criar um UpdateDefinition
objeto para um desses operadores, chame o método correspondente a partir da Builders.Update
propriedade. As seções a seguir descrevem esses métodos em mais detalhes.
After you create an UpdateDefinition
objeto, pass it to the UpdateOne()
or UpdateOneAsync()
method. Para obter mais informações sobre esses métodos, consulte a páginaAtualizar um.
Observação
Sobrecargas de método
Muitos dos métodos nesta página têm múltiplas sobrecargas. Os exemplos deste guia mostram apenas uma definição de cada método. Para obter mais informações sobre as sobrecargas disponíveis, consulte a documentação da API.
Dados de amostra
Os exemplos neste guia utilizam a coleção do restaurants
a partir do banco de dados do sample_restaurants
. Os documentos nesta coleção usam as seguintes classes Restaurant
, Address
e GradeEntry
como modelos:
public class Restaurant { public ObjectId Id { get; set; } public string Name { get; set; } [ ] public string RestaurantId { get; set; } public string Cuisine { get; set; } public Address Address { get; set; } public string Borough { get; set; } public List<GradeEntry> Grades { get; set; } }
public class Address { public string Building { get; set; } [ ] public double[] Coordinates { get; set; } public string Street { get; set; } [ ] public string ZipCode { get; set; } }
public class GradeEntry { public DateTime Date { get; set; } public string Grade { get; set; } public float? Score { get; set; } }
Observação
Os documentos na collection restaurants
usam a convenção de nomenclatura snake-case. Os exemplos neste guia usam um ConventionPack
para desserializar os campos na coleção em maiúsculas e minúsculas Pascal e mapeá-los para as propriedades na classe Restaurant
.
Para saber mais sobre serialização personalizada, consulte Serialização personalizada.
Essa coleção é dos conjuntos de dados de amostra fornecidos pelo Atlas. Consulte o Quick Start para saber como criar um cluster MongoDB gratuito e carregar esses dados de amostra.
Adicionar um valor
Para adicionar um valor ao final de uma array, chame o método Builders.Update.Push()
. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array ao qual adicionar um valor. Tipo de dados: |
| O valor a ser adicionado ao final do campo de array . Tipo de dados: |
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var update = Builders<Restaurant>.Update .Push(restaurant => restaurant.Grades, new GradeEntry() { Date = DateTime.Now, Grade = "A", Score = 96 }); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var update = Builders<Restaurant>.Update .Push(restaurant => restaurant.Grades, new GradeEntry() { Date = DateTime.Now, Grade = "A", Score = 96 }); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Dica
Configurar a operação push
Para adicionar um valor em uma posição específica em uma array ou para classificar ou dividir a array após atualizá-la, chame o método PushEach().
Para adicionar um valor ao final de uma array, mas somente se ele ainda não existir na array, chame o Builders.Update.AddToSet()
método. O MongoDB Server determina se o valor já existe na array comparando a representação BSON do valor com a representação BSON de cada outro elemento na array.
O método AddToSet()
aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array ao qual adicionar um valor. Tipo de dados: |
| O valor a ser adicionado ao final do campo de array . Tipo de dados: |
The following code exemplo calls the AddToSet()
method to re-add the first GradeEntry
objeto to the Grades
array in the matching documento. Como o valor já existe na array, a operação de atualização não faz nada.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var firstGradeEntry = _restaurantsCollection.Find(filter).FirstOrDefault().Grades[0]; var update = Builders<Restaurant>.Update .AddToSet(restaurant => restaurant.Grades, firstGradeEntry); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var firstGradeEntry = _restaurantsCollection.Find(filter).FirstOrDefault().Grades[0]; var update = Builders<Restaurant>.Update .AddToSet(restaurant => restaurant.Grades, firstGradeEntry); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Adicionar vários valores
Para adicionar vários valores a uma array, chame o método Builders.Update.PushEach()
. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array ao qual adicionar um ou mais valores. Tipo de dados: |
| Os valores a serem adicionados ao campo de array . Tipo de dados: |
| O número de elementos a serem mantidos na array, contados desde o início da array após as atualizações. Se o valor for negativo, o método manterá o número especificado de elementos do final da array. Tipo de dados: |
| A posição na array na qual adicionar os valores. Por padrão, o método adiciona os valores ao final da array. Tipo de dados: |
| Um objeto Tipo de dados: SortDefinition<TItem> |
The following code exemplo uses the PushEach()
method to add two new GradeEntry
objects to the start of the Grades
array in the matching documento. Em seguida, ele classifica os elementos da array em ordem decrescente pelos valores de seus campos Score
.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.Now, Grade = "A", Score = 95 }, new GradeEntry { Date = DateTime.Now, Grade = "B+", Score = 89,} }; var scoreSort = Builders<GradeEntry>.Sort.Descending(g => g.Score); var update = Builders<Restaurant>.Update.PushEach( "Grades", newGrades, position: 0, sort: scoreSort); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.Now, Grade = "A", Score = 95 }, new GradeEntry { Date = DateTime.Now, Grade = "B+", Score = 89,} }; var scoreSort = Builders<GradeEntry>.Sort.Descending(g => g.Score); var update = Builders<Restaurant>.Update.PushEach( "Grades", newGrades, position: 0, sort: scoreSort); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Para adicionar vários valores a uma array, mas somente se eles ainda não existirem na array, chame o Builders.Update.AddToSetEach()
método. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array ao qual adicionar um ou mais valores. Tipo de dados: |
| Os valores a serem adicionados ao campo de array . Tipo de dados: |
The following code exemplo calls the AddToSetEach()
method to re-add the first and second GradeEntry
objects to the Grades
array in the matching documento. Como esses valores já existem na array, a operação de atualização não faz nada.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var doc = _restaurantsCollection.Find(filter).FirstOrDefault(); var firstGradeEntries = new List<GradeEntry> { doc.Grades[0], doc.Grades[1] }; var update = Builders<Restaurant>.Update .AddToSetEach(restaurant => restaurant.Grades, firstGradeEntries); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var doc = _restaurantsCollection.Find(filter).FirstOrDefault(); var firstGradeEntries = new List<GradeEntry> { doc.Grades[0], doc.Grades[1] }; var update = Builders<Restaurant>.Update .AddToSetEach(restaurant => restaurant.Grades, firstGradeEntries); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Remove Values
As seções seguintes explicam como remover valores de um campo de array.
Primeiro valor
Para remover o primeiro valor de uma array, chame o método Builders.Update.PopFirst()
. Este método aceita o seguinte parâmetro:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array do qual remover o primeiro valor. Tipo de dados: |
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var update = Builders<Restaurant>.Update .PopFirst(restaurant => restaurant.Grades); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var update = Builders<Restaurant>.Update .PopFirst(restaurant => restaurant.Grades); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Valor Última
Para remover o último valor de uma array, chame o método Builders.Update.PopLast()
: Este método aceita o seguinte parâmetro:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array do qual remover o último valor. Tipo de dados: |
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var update = Builders<Restaurant>.Update .PopLast(restaurant => restaurant.Grades); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var update = Builders<Restaurant>.Update .PopLast(restaurant => restaurant.Grades); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Todas as instâncias de um valor
Para remover todas as instâncias de um valor específico de uma array, chame o método Builders.Update.Pull()
. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array do qual remover os valores. Tipo de dados: |
| O valor a ser removido do campo de array . Tipo de dados: |
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Add duplicate values to Grades array var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95 }, new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95,} }; var addUpdate = Builders<Restaurant>.Update .PushEach("Grades", newGrades); _restaurantsCollection.UpdateOne(filter, addUpdate); // Remove duplicates from Grades array var pullUpdate = Builders<Restaurant>.Update .Pull(restaurant => restaurant.Grades, newGrades[0]); var result = _restaurantsCollection.UpdateOne(filter, pullUpdate); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Add duplicate values to Grades array var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95 }, new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95,} }; var addUpdate = Builders<Restaurant>.Update .PushEach("Grades", newGrades); await _restaurantsCollection.UpdateOneAsync(filter, addUpdate); // Remove duplicates from Grades array var pullUpdate = Builders<Restaurant>.Update .Pull(restaurant => restaurant.Grades, newGrades[0]); var result = await _restaurantsCollection.UpdateOneAsync(filter, pullUpdate); return result;
Todas as instâncias de vários valores
Para remover todas as instâncias de mais de um valor específico de uma array, chame o método Builders.Update.PullAll()
. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array do qual remover os valores. Tipo de dados: |
| Os valores a serem removidos do campo de array . Tipo de dados: |
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Add duplicate values to Grades array var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95 }, new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95,}, new GradeEntry { Date = DateTime.MinValue, Grade = "B", Score = 85 }, new GradeEntry { Date = DateTime.MinValue, Grade = "B", Score = 85,} }; var addUpdate = Builders<Restaurant>.Update .PushEach("Grades", newGrades); _restaurantsCollection.UpdateOne(filter, addUpdate); // Remove duplicates from Grades array var gradesToRemove = new List<GradeEntry> { newGrades[0], newGrades[2] }; var pullUpdate = Builders<Restaurant>.Update .PullAll(restaurant => restaurant.Grades, gradesToRemove); var result = _restaurantsCollection.UpdateOne(filter, pullUpdate); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Add duplicate values to Grades array var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95 }, new GradeEntry { Date = DateTime.MinValue, Grade = "A", Score = 95,}, new GradeEntry { Date = DateTime.MinValue, Grade = "B", Score = 85 }, new GradeEntry { Date = DateTime.MinValue, Grade = "B", Score = 85,} }; var addUpdate = Builders<Restaurant>.Update .PushEach("Grades", newGrades); await _restaurantsCollection.UpdateOneAsync(filter, addUpdate); // Remove duplicates from Grades array var gradesToRemove = new List<GradeEntry> { newGrades[0], newGrades[2] }; var pullUpdate = Builders<Restaurant>.Update .PullAll(restaurant => restaurant.Grades, gradesToRemove); var result = await _restaurantsCollection.UpdateOneAsync(filter, pullUpdate); return result;
Todos os valores que correspondem a uma condição
Para remover todos os valores que correspondem a uma condição específica de uma array, chame o método Builders.Update.PullFilter()
. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array do qual remover os valores. Tipo de dados: |
| Um filtro de query que especifica a condição para os valores a serem removidos. Tipo de dados: FilterDefinition<TItem> |
O exemplo de código a seguir usa o método PullFilter()
para remover todos os objetos GradeEntry
em que o valor Grade
é "F"
da array Grades
nos documentos correspondentes:
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Add GradeEntry values with "Grade = F" to Grades array var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 10 }, new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 21,}, new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 47 }, new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 6,} }; var addUpdate = Builders<Restaurant>.Update .PushEach("Grades", newGrades); _restaurantsCollection.UpdateOne(filter, addUpdate); // Remove all "Grade = F" values from Grades array var pullUpdate = Builders<Restaurant>.Update .PullFilter(restaurant => restaurant.Grades, gradeEntry => gradeEntry.Grade == "F"); var result = _restaurantsCollection.UpdateOne(filter, pullUpdate); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Add GradeEntry values with "Grade = F" to Grades array var newGrades = new List<GradeEntry> { new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 10 }, new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 21,}, new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 47 }, new GradeEntry { Date = DateTime.Now, Grade = "F", Score = 6,} }; var addUpdate = Builders<Restaurant>.Update .PushEach("Grades", newGrades); await _restaurantsCollection.UpdateOneAsync(filter, addUpdate); // Remove all "Grade = F" values from Grades array var pullUpdate = Builders<Restaurant>.Update .PullFilter(restaurant => restaurant.Grades, gradeEntry => gradeEntry.Grade == "F"); var result = await _restaurantsCollection.UpdateOneAsync(filter, pullUpdate); return result;
Atualizar valores correspondentes
Para atualizar um valor em um campo de array, chame o método Builders.Update.Set()
. Este método aceita os seguintes parâmetros:
Parâmetro | Descrição |
---|---|
| Uma expressão que especifica o campo de array a ser atualizado. Tipo de dados: |
| O novo valor a ser definido no campo de array . Tipo de dados: |
Você pode usar o operador posicional com o Set()
método para consultar e atualizar valores específicos na array. Se você estiver usando o3 provedor LINQ, o driver .NET/C# também permitirá a sintaxe LINQ no lugar do operador posicional.
As seções seguintes descrevem maneiras diferentes de atualizar valores correspondentes em um campo de array.
Primeiro valor correspondente
Para atualizar o primeiro valor em uma array, você pode usar o operador posicional ($
) ou a sintaxe LINQ. Selecione uma aba Positional Operator ou LINQ para ver a sintaxe correspondente.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli") & Builders<Restaurant>.Filter.Eq("grades.grade", "A"); // Set Score = 100 in first GradeEntry where Grade = "A" var update = Builders<Restaurant>.Update .Set("grades.$.score", 100); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
Observação
Para usar o operador posicional, o campo de array deve fazer parte do filtro de query.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli") & Builders<Restaurant>.Filter.Eq("grades.grade", "A"); // Set Score = 100 in first GradeEntry where Grade = "A" var update = Builders<Restaurant>.Update .Set("grades.$.score", 100); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Observação
Para usar o operador posicional, o campo de array deve fazer parte do filtro de query.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli") & Builders<Restaurant>.Filter.Eq("grades.grade", "A"); var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Grades.FirstMatchingElement().Score, 100); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli") & Builders<Restaurant>.Filter.Eq("grades.grade", "A"); var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Grades.FirstMatchingElement().Score, 100); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Todos os valores correspondentes
Para atualizar todos os valores em uma array que correspondam a uma condição especificada, você pode usar o operador posicional filtrado ($[<identifier>]
) ou a sintaxe LINQ. Selecione uma aba Positional Operator ou LINQ para ver a sintaxe correspondente.
O exemplo seguinte utiliza o método Set()
e o operador posicional filtrado para atualizar a propriedade Score
de todos os objetos GradeEntry
correspondentes na array Grades
para 100 em todos os documentos correspondentes.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var arrayFilters = new List<ArrayFilterDefinition> { new BsonDocumentArrayFilterDefinition<Restaurant>( new BsonDocument { { "gradeEntry.score", new BsonDocument { { "$gte", 94} } } }) }; // Set Grade = "A" in all GradeEntry objects where Score >= 94 var update = Builders<Restaurant>.Update .Set("grades.$[gradeEntry].grade", "A"); var updateOptions = new UpdateOptions { ArrayFilters = arrayFilters }; var result = _restaurantsCollection.UpdateOne(filter, update, updateOptions); return result;
O exemplo seguinte utiliza o método Set()
e o operador posicional filtrado para atualizar a propriedade Score
de todos os objetos GradeEntry
correspondentes na array Grades
para 100 em todos os documentos correspondentes.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var arrayFilters = new List<ArrayFilterDefinition> { new BsonDocumentArrayFilterDefinition<Restaurant>( new BsonDocument { { "gradeEntry.score", new BsonDocument { { "$gte", 94} } } }) }; // Set Grade = "A" in all GradeEntry objects where Score >= 94 var update = Builders<Restaurant>.Update .Set("grades.$[gradeEntry].grade", "A"); var updateOptions = new UpdateOptions { ArrayFilters = arrayFilters }; var result = await _restaurantsCollection.UpdateOneAsync(filter, update, updateOptions); return result;
O exemplo a seguir usa os métodos Set()
e AllMatchingElements()
para atualizar a propriedade Score
de todos os objetos GradeEntry
correspondentes na array Grades
para 100 em todos os documentos correspondentes.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var arrayFilters = new List<ArrayFilterDefinition> { new BsonDocumentArrayFilterDefinition<Restaurant>( new BsonDocument { { "gradeEntry.score", new BsonDocument { { "$gte", 94} } } }) }; // Set Grade = "A" in all GradeEntry objects where Score >= 94 var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Grades.AllMatchingElements("gradeEntry").Grade, "A"); var updateOptions = new UpdateOptions { ArrayFilters = arrayFilters }; var result = _restaurantsCollection.UpdateOne(filter, update, updateOptions); return result;
O exemplo a seguir usa os métodos Set()
e AllMatchingElements()
para atualizar a propriedade Score
de todos os objetos GradeEntry
correspondentes na array Grades
para 100 em todos os documentos correspondentes.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); var arrayFilters = new List<ArrayFilterDefinition> { new BsonDocumentArrayFilterDefinition<Restaurant>( new BsonDocument { { "gradeEntry.score", new BsonDocument { { "$gte", 94} } } }) }; // Set Grade = "A" in all GradeEntry objects where Score >= 94 var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Grades.AllMatchingElements("gradeEntry").Grade, "A"); var updateOptions = new UpdateOptions { ArrayFilters = arrayFilters }; var result = await _restaurantsCollection.UpdateOneAsync(filter, update, updateOptions); return result;
All Values
Para atualizar todos os valores em uma array que correspondam a um filtro de query, você pode usar o operador posicional ($[]
) ou a sintaxe LINQ. Selecione uma aba Positional Operator ou LINQ para ver a sintaxe correspondente.
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Set Score = 100 in all GradeEntry objects var update = Builders<Restaurant>.Update .Set("grades.$[].score", 100); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Set Score = 100 in all GradeEntry objects var update = Builders<Restaurant>.Update .Set("grades.$[].score", 100); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Set Score = 100 in all GradeEntry objects var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Grades.AllElements().Score, 100); var result = _restaurantsCollection.UpdateOne(filter, update); return result;
var filter = Builders<Restaurant>.Filter.Eq("name", "Downtown Deli"); // Set Score = 100 in all GradeEntry objects var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Grades.AllElements().Score, 100); var result = await _restaurantsCollection.UpdateOneAsync(filter, update); return result;
Documentação da API
Para obter mais informações sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API: