Поделиться через

Использование базы данных документов Azure Cosmos DB в Xamarin.Forms

  • Статья

База данных документов Azure Cosmos DB — это база данных NoSQL, которая обеспечивает доступ к документам JSON с низкой задержкой, предлагая быструю, высокодоступную, масштабируемую службу баз данных для приложений, требующих простого масштабирования и глобального реплика. В этой статье объясняется, как использовать клиентская библиотека .NET Standard Azure Cosmos DB для интеграции базы данных документов Azure Cosmos DB в Xamarin.Forms приложение.

Видео Microsoft Azure Cosmos DB

Учетная запись базы данных документов Azure Cosmos DB может быть подготовлена с помощью подписки Azure. Каждая учетная запись базы данных может иметь ноль или больше баз данных. База данных документов в Azure Cosmos DB — это логический контейнер для коллекций документов и пользователей.

База данных документов Azure Cosmos DB может содержать ноль или более коллекций документов. Каждая коллекция документов может иметь другой уровень производительности, что позволяет указать большую пропускную способность для часто доступных коллекций и меньше пропускной способности для редко доступных коллекций.

Каждая коллекция документов состоит из нуля или нескольких документов JSON. Документы в коллекции являются бесплатными по схеме, поэтому не требуется совместно использовать одну структуру или поля. Так как документы добавляются в коллекцию документов, Azure Cosmos DB автоматически индексирует их и становится доступным для запроса.

В целях разработки база данных документов также может использоваться с помощью эмулятора. С помощью эмулятора приложения можно разрабатывать и тестировать локально, не создавая подписку Azure или не создавая затраты. Дополнительные сведения об эмуляторе см. в статье "Разработка локально с помощью эмулятора Azure Cosmos DB".

В этой статье и сопроводительном примере приложения демонстрируется приложение списка todo, в котором задачи хранятся в базе данных документов Azure Cosmos DB. Дополнительные сведения о примере приложения см. в разделе "Общие сведения о примере".

Дополнительные сведения о Azure Cosmos DB см. в документации по Azure Cosmos DB.

Примечание.

Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начать работу.

Настройка

Процесс интеграции базы данных документов Azure Cosmos DB в Xamarin.Forms приложение выглядит следующим образом:

  1. Создайте учетную запись Azure Cosmos DB. Дополнительные сведения см. в статье "Создание учетной записи Azure Cosmos DB".
  2. Добавьте пакет NuGet клиентской библиотеки .NET Standard Azure Cosmos DB в проекты платформы Xamarin.Forms в решении.
  3. Добавьте using директивы для Microsoft.Azure.DocumentsMicrosoft.Azure.Documents.Clientпространств имен и Microsoft.Azure.Documents.Linq пространств имен в классы, которые будут получать доступ к учетной записи Azure Cosmos DB.

После выполнения этих действий клиентская библиотека .NET Standard Azure Cosmos DB может использоваться для настройки и выполнения запросов к базе данных документов.

Примечание.

Клиентская библиотека .NET Standard Azure Cosmos DB может быть установлена только в проекты платформы, а не в проект переносимой библиотеки классов (PCL). Поэтому пример приложения — это проект общего доступа (SAP), чтобы избежать дублирования кода. DependencyService Однако класс можно использовать в проекте PCL для вызова клиентской библиотеки Azure Cosmos DB .NET Standard, содержащегося в проектах, зависящих от платформы.

Использование учетной записи Azure Cosmos DB

Тип DocumentClient инкапсулирует конечную точку, учетные данные и политику подключения, используемую для доступа к учетной записи Azure Cosmos DB, и используется для настройки и выполнения запросов к учетной записи. В следующем примере кода показано, как создать экземпляр этого класса:

DocumentClient client = new DocumentClient(new Uri(Constants.EndpointUri), Constants.PrimaryKey);

Uri и первичный ключ Azure Cosmos DB должны быть предоставлены конструктору DocumentClient . Их можно получить на портале Azure. Дополнительные сведения см. в Подключение учетной записи Azure Cosmos DB.

Создание базы данных

База данных документов — это логический контейнер для коллекций документов и пользователей, и его можно создать на портале Azure или программным способом DocumentClient.CreateDatabaseIfNotExistsAsync :

public async Task CreateDatabase(string databaseName)
{
  ...
  await client.CreateDatabaseIfNotExistsAsync(new Database
  {
    Id = databaseName
  });
  ...
}

Метод CreateDatabaseIfNotExistsAsync задает Database объект в качестве аргумента, с Database объектом, указывающим имя базы данных в качестве его Id свойства. Метод CreateDatabaseIfNotExistsAsync создает базу данных, если она не существует, или возвращает базу данных, если она уже существует. Однако пример приложения игнорирует все данные, возвращаемые методом CreateDatabaseIfNotExistsAsync .

Примечание.

Метод CreateDatabaseIfNotExistsAsync возвращает Task<ResourceResponse<Database>> объект, а код состояния ответа можно проверка, чтобы определить, была ли создана база данных или была возвращена существующая база данных.

Создание коллекции документов

Коллекция документов — это контейнер для документов JSON, который можно создать на портале Azure или программным способом DocumentClient.CreateDocumentCollectionIfNotExistsAsync :

public async Task CreateDocumentCollection(string databaseName, string collectionName)
{
  ...
  // Create collection with 400 RU/s
  await client.CreateDocumentCollectionIfNotExistsAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    new DocumentCollection
    {
      Id = collectionName
    },
    new RequestOptions
    {
      OfferThroughput = 400
    });
  ...
}

Для CreateDocumentCollectionIfNotExistsAsync метода требуются два обязательных аргумента: имя базы данных, указанное как Uriобъект.DocumentCollection Объект DocumentCollection представляет коллекцию документов, имя которой указано свойством Id . Метод CreateDocumentCollectionIfNotExistsAsync создает коллекцию документов, если она не существует, или возвращает коллекцию документов, если она уже существует. Однако пример приложения игнорирует все данные, возвращаемые методом CreateDocumentCollectionIfNotExistsAsync .

Примечание.

Метод CreateDocumentCollectionIfNotExistsAsync возвращает Task<ResourceResponse<DocumentCollection>> объект, а код состояния ответа можно проверка, чтобы определить, была ли создана коллекция документов или была возвращена существующая коллекция документов.

CreateDocumentCollectionIfNotExistsAsync При необходимости метод также может указать объект, который инкапсулирует параметры, которые можно указать RequestOptions для запросов, выданных учетной записи Azure Cosmos DB. Свойство RequestOptions.OfferThroughput используется для определения уровня производительности коллекции документов, а в примере приложения — 400 единиц запросов в секунду. Это значение должно быть увеличено или уменьшено в зависимости от того, будет ли коллекция часто или редко доступна.

Внимание

Обратите внимание, что CreateDocumentCollectionIfNotExistsAsync метод создаст новую коллекцию с зарезервированной пропускной способностью, которая имеет последствия для ценообразования.

Получение документов коллекции документов

Содержимое коллекции документов можно получить путем создания и выполнения запроса документа. Запрос документа создается с DocumentClient.CreateDocumentQuery помощью метода:

public async Task<List<TodoItem>> GetTodoItemsAsync()
{
  ...
  var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
            .AsDocumentQuery();
  while (query.HasMoreResults)
  {
    Items.AddRange(await query.ExecuteNextAsync<TodoItem>());
  }
  ...
}

Этот запрос асинхронно извлекает все документы из указанной List<TodoItem> коллекции и помещает документы в коллекцию для отображения.

Метод CreateDocumentQuery<T> задает Uri аргумент, представляющий коллекцию, которая должна запрашиваться для документов. В этом примере collectionLink переменная представляет собой поле уровня класса, указывающее Uri , что представляет коллекцию документов для получения документов из:

Uri collectionLink = UriFactory.CreateDocumentCollectionUri(Constants.DatabaseName, Constants.CollectionName);

Метод CreateDocumentQuery<T> создает запрос, который выполняется синхронно и возвращает IQueryable<T> объект. AsDocumentQuery Однако метод преобразует объект в IQueryable<T> объектIDocumentQuery<T>, который может выполняться асинхронно. Асинхронный запрос выполняется с IDocumentQuery<T>.ExecuteNextAsync помощью метода, который извлекает следующую страницу результатов из базы данных документа с IDocumentQuery<T>.HasMoreResults свойством, указывающим, есть ли дополнительные результаты, возвращаемые из запроса.

Документы можно отфильтровать на стороне сервера, включив Where предложение в запрос, которое применяет предикат фильтрации к запросу к коллекции документов:

var query = client.CreateDocumentQuery<TodoItem>(collectionLink)
          .Where(f => f.Done != true)
          .AsDocumentQuery();

Этот запрос извлекает все документы из коллекции, свойство которого Done равно false.

Вставка документа в коллекцию документов

Документы — это пользовательское содержимое JSON, и его можно вставить в коллекцию документов с DocumentClient.CreateDocumentAsync помощью метода:

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.CreateDocumentAsync(collectionLink, item);
  ...
}

Метод CreateDocumentAsync задает Uri аргумент, представляющий коллекцию, в которую необходимо вставить документ, и object аргумент, представляющий документ для вставки.

Замена документа в коллекции документов

Документы можно заменить в коллекции документов методом DocumentClient.ReplaceDocumentAsync :

public async Task SaveTodoItemAsync(TodoItem item, bool isNewItem = false)
{
  ...
  await client.ReplaceDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, item.Id), item);
  ...
}

Метод ReplaceDocumentAsync задает Uri аргумент, представляющий документ в коллекции, который должен быть заменен, и object аргумент, представляющий обновленные данные документа.

Удаление документа из коллекции документов

Документ можно удалить из коллекции документов с DocumentClient.DeleteDocumentAsync помощью метода:

public async Task DeleteTodoItemAsync(string id)
{
  ...
  await client.DeleteDocumentAsync(UriFactory.CreateDocumentUri(Constants.DatabaseName, Constants.CollectionName, id));
  ...
}

Метод DeleteDocumentAsync задает Uri аргумент, представляющий документ в коллекции, который должен быть удален.

Удаление коллекции документов

Коллекцию документов можно удалить из базы данных с DocumentClient.DeleteDocumentCollectionAsync помощью метода:

await client.DeleteDocumentCollectionAsync(collectionLink);

Метод DeleteDocumentCollectionAsync задает Uri аргумент, представляющий коллекцию документов, которую необходимо удалить. Обратите внимание, что при вызове этого метода также будут удалены документы, хранящиеся в коллекции.

Удаление базы данных

Базу данных можно удалить из учетной записи базы данных Azure Cosmos DB с DocumentClient.DeleteDatabaesAsync помощью метода:

await client.DeleteDatabaseAsync(UriFactory.CreateDatabaseUri(Constants.DatabaseName));

Метод DeleteDatabaseAsync задает Uri аргумент, представляющий базу данных для удаления. Обратите внимание, что при вызове этого метода также будут удалены коллекции документов, хранящиеся в базе данных, и документы, хранящиеся в коллекциях документов.

Итоги

В этой статье объясняется, как использовать клиентская библиотека .NET Standard Azure Cosmos DB для интеграции базы данных документов Azure Cosmos DB в Xamarin.Forms приложение. База данных документов Azure Cosmos DB — это база данных NoSQL, которая обеспечивает доступ к документам JSON с низкой задержкой, предлагая быструю, высокодоступную, масштабируемую службу баз данных для приложений, требующих простого масштабирования и глобального реплика.