Краткое руководство. Создание приложения API таблиц с помощью пакета SDK .NET и Azure Cosmos DB

ПРИМЕНИМО К: API таблиц

В этом руководстве показано, как использовать .NET и API таблицы Azure Cosmos DB для создания приложения путем клонирования примера с сайта GitHub. Кроме того, здесь показано, как создать учетную запись Azure Cosmos DB и использовать обозреватель данных для создания таблиц и сущностей на веб-портале Azure.

Предварительные требования

Если вы еще не установили Visual Studio 2019, можете скачать и использовать бесплатную среду Visual Studio 2019 Community Edition. При установке Visual Studio необходимо включить возможность разработки для Azure.

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

Создание учетной записи базы данных

  1. В новом окне браузера войдите на портал Azure.

  2. В меню слева выберите Создать ресурс.

    Создание ресурса на портале Azure

  3. На странице New (Новый) выберите Базы данных > Azure Cosmos DB.

    Область "Базы данных" на портале Azure

  4. На странице Создание учетной записи Azure Cosmos DB введите параметры для новой учетной записи Azure Cosmos DB.

    Параметр Значение Описание
    Подписка Ваша подписка Вы подписку Azure, которую нужно использовать для этой учетной записи Azure Cosmos DB.
    Группа ресурсов Щелкните Создать, а затем введите имя учетной записи. Выберите Создать. Затем введите новое имя группы ресурсов для учетной записи. Для удобства можно использовать то же имя, которое присвоено учетной записи Azure Cosmos DB.
    Имя учетной записи Уникальное имя Введите уникальное имя для идентификации вашей учетной записи Azure Cosmos DB.

    Имя может содержать только строчные буквы, цифры и дефисы. Его длина должна быть от 3 до 44 знаков.
    API Таблица API определяет тип учетной записи, которую нужно создать. Azure Cosmos DB предоставляет пять API: API Core (SQL) для баз данных документов, API Gremlin для графовых баз данных, API MongoDB для баз данных документов, API таблиц Azure и API Cassandra. Для каждого API требуется создать отдельную учетную запись.

    Выберите Таблица Azure, так как в этом кратком руководстве создается таблица, которая работает с API таблиц.

    Подробные сведения об API таблиц.
    Расположение Ближайший к пользователям регион Выберите географическое расположение для размещения учетной записи Azure Cosmos DB. Используйте ближайшее к пользователям расположение, чтобы предоставить им максимально быстрый доступ к данным.
    Режим емкости "Подготовленная пропускная способность" или "Бессерверный" Выберите Подготовленная пропускная способность, чтобы создать учетную запись в режиме подготовленной пропускной способности. Выберите Бессерверный, чтобы создать учетную запись в режиме Бессерверный.

    Вы можете не изменять значения по умолчанию для параметров Геоизбыточность и Записи в нескольких регионах (Отключить), чтобы избежать дополнительных затрат, и пропустить разделы Сеть и Теги.

  5. Выберите Просмотр и создание. После завершения проверки нажмите Создать, чтобы создать учетную запись.

    Страница "Новая учетная запись" для Azure Cosmos DB

  6. Создание учетной записи занимает несколько минут. Вы увидите сообщение Развертывание выполняется. Дождитесь завершения развертывания, а затем нажмите кнопку Перейти к ресурсу.

    Область "Уведомления" на портале Azure

Добавление таблицы

Теперь вы можете использовать средство обозреватель данных на портале Azure для создания базы данных и таблицы.

  1. Выберите Data Explorer > Создать таблицу.

    Справа отобразится область Добавление таблицы (вам может потребоваться прокрутить вправо, чтобы увидеть ее).

    Обозреватель данных на портале Azure

  2. На странице Добавление таблицы введите параметры для новой таблицы.

    Параметр Рекомендуемое значение Описание
    Идентификатор таблицы Пример таблицы Идентификатор новой таблицы. Для имен таблиц предусмотрены те же требования к знакам, что и для идентификаторов баз данных. Имя базы данных может иметь длину от 1 до 255 символов и не может содержать / \ # ? или пробел.
    Пропускная способность 400 ЕЗ Укажите для пропускной способности 400 единиц запросов в секунду. Чтобы сократить задержку, позже вы можете увеличить масштаб пропускной способности.
  3. Щелкните ОК.

  4. В обозревателе данных отобразится новая база данных и таблица.

    Обозреватель данных на портале Azure с новой базой данных и коллекцией

Добавление демонстрационных данных

Теперь вы можете добавить данные в созданную таблицу с помощью обозревателя данных.

  1. В Data Explorer разверните пример таблицы, выберите Сущности, а затем — Добавление сущности.

    Создание сущностей в обозревателе данных на портале Azure

  2. Теперь добавьте данные в поля значений PartitionKey и RowKey и щелкните Добавление сущности.

    Указание ключа секции и ключа строки для новой сущности

    Теперь вы можете добавить больше сущностей в свою таблицу, изменить эти сущности или выполнить запрос данных в обозревателе данных. В обозревателе данных вы можете масштабировать пропускную способность, а также добавлять хранимые процедуры, определенные пользователем функции и триггеры в свою таблицу.

Клонирование примера приложения

Теперь необходимо клонировать приложение "Таблица" из GitHub. Задайте строку подключения и выполните ее. Вы узнаете, как можно упростить работу с данными программным способом.

  1. Откройте командную строку, создайте папку git-samples, а затем закройте окно командной строки.

    md "C:\git-samples"
    
  2. Откройте окно терминала git, например git bash, и выполните команду cd, чтобы перейти в новую папку для установки примера приложения.

    cd "C:\git-samples"
    
  3. Выполните команду ниже, чтобы клонировать репозиторий с примером. Эта команда создает копию примера приложения на локальном компьютере.

    git clone https://github.com/Azure-Samples/azure-cosmos-table-dotnet-core-getting-started.git
    

Совет

Более подробное пошаговое руководство по аналогичному коду см. в статье с примером API таблиц для Cosmos DB.

Открытие примера приложения в Visual Studio

  1. В Visual Studio в меню Файл нажмите Открыть и выберите проект или решение.

    Открытие решения

  2. Перейдите к папке, в которую вы клонировали пример приложения, и откройте файл TableStorage.sln.

Просмотр кода

Это необязательный шаг. Если вы хотите узнать, как создать в коде ресурсы базы данных, изучите приведенные ниже фрагменты кода. Если вас это не интересует, можете сразу переходить к разделу Обновление строки подключения в этом документе.

  • В следующем коде показано, как создать таблицу в службе хранилища Azure.

    public static async Task<CloudTable> CreateTableAsync(string tableName)
    {
        string storageConnectionString = AppSettings.LoadAppSettings().StorageConnectionString;
    
        // Retrieve storage account information from connection string.
        CloudStorageAccount storageAccount = CreateStorageAccountFromConnectionString(storageConnectionString);
    
        // Create a table client for interacting with the table service
        CloudTableClient tableClient = storageAccount.CreateCloudTableClient(new TableClientConfiguration());
    
        Console.WriteLine("Create a Table for the demo");
    
        // Create a table client for interacting with the table service 
        CloudTable table = tableClient.GetTableReference(tableName);
        if (await table.CreateIfNotExistsAsync())
        {
            Console.WriteLine("Created Table named: {0}", tableName);
        }
        else
        {
            Console.WriteLine("Table {0} already exists", tableName);
        }
    
        Console.WriteLine();
        return table;
    }
    
  • В следующем коде показано, как вставить данные в таблицу.

    public static async Task<CustomerEntity> InsertOrMergeEntityAsync(CloudTable table, CustomerEntity entity)
    {
        if (entity == null)
        {
            throw new ArgumentNullException("entity");
        }
    
        try
        {
            // Create the InsertOrReplace table operation
            TableOperation insertOrMergeOperation = TableOperation.InsertOrMerge(entity);
    
            // Execute the operation.
            TableResult result = await table.ExecuteAsync(insertOrMergeOperation);
            CustomerEntity insertedCustomer = result.Result as CustomerEntity;
    
            if (result.RequestCharge.HasValue)
            {
                Console.WriteLine("Request Charge of InsertOrMerge Operation: " + result.RequestCharge);
            }
    
            return insertedCustomer;
        }
        catch (StorageException e)
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
    
  • В следующем коде показано, как выполнить запрос данных из таблицы.

    public static async Task<CustomerEntity> RetrieveEntityUsingPointQueryAsync(CloudTable table, string partitionKey, string rowKey)
    {
        try
        {
            TableOperation retrieveOperation = TableOperation.Retrieve<CustomerEntity>(partitionKey, rowKey);
            TableResult result = await table.ExecuteAsync(retrieveOperation);
            CustomerEntity customer = result.Result as CustomerEntity;
            if (customer != null)
            {
                Console.WriteLine("\t{0}\t{1}\t{2}\t{3}", customer.PartitionKey, customer.RowKey, customer.Email, customer.PhoneNumber);
            }
    
            if (result.RequestCharge.HasValue)
            {
                Console.WriteLine("Request Charge of Retrieve Operation: " + result.RequestCharge);
            }
    
            return customer;
        }
        catch (StorageException e)
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
    
  • В следующем коде показано, как удалить данные из таблицы.

    public static async Task DeleteEntityAsync(CloudTable table, CustomerEntity deleteEntity)
    {
        try
        {
            if (deleteEntity == null)
            {
                throw new ArgumentNullException("deleteEntity");
            }
    
            TableOperation deleteOperation = TableOperation.Delete(deleteEntity);
            TableResult result = await table.ExecuteAsync(deleteOperation);
    
            if (result.RequestCharge.HasValue)
            {
                Console.WriteLine("Request Charge of Delete Operation: " + result.RequestCharge);
            }
    
        }
        catch (StorageException e)
        {
            Console.WriteLine(e.Message);
            Console.ReadLine();
            throw;
        }
    }
    

Обновление строки подключения

Теперь вернитесь на портал Azure, чтобы получить данные строки подключения. Скопируйте эти данные в приложение. Так вы обеспечите обмен данными между приложением и размещенной базой данных.

  1. На портале Azure щелкните Строка подключения. Используйте кнопку копирования в правой части окна, чтобы скопировать основную строку подключения.

    Просмотр и копирование основной строки подключения на панели строки подключения

  2. Откройте файл Settings.json в Visual Studio.

  3. Вставьте значение Первичная строка подключения, полученное на портале, вместо значения параметра StorageConnectionString. Значение нужно вставлять в кавычках.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. Чтобы сохранить файл Settings.json, нажмите CTRL+S.

Теперь приложение со всеми сведениями, необходимыми для взаимодействия с Azure Cosmos DB, обновлено.

Создание и развертывание приложения

  1. Правой кнопкой мыши щелкните проект CosmosTableSamples в обозревателе решений Visual Studio и выберите Управление пакетами NuGet.

    Управление пакетами NuGet

  2. В поле Обзор NuGet введите Microsoft.Azure.Cosmos.Table. Это запрос для поиска клиентской библиотеки API таблицы Cosmos DB. Обратите внимание, что на данный момент эта библиотека доступна только для .NET Framework и .NET Standard.

    Вкладка &quot;Обзор&quot; в NuGet

  3. Щелкните Установить, чтобы установить библиотеку Microsoft.Azure.Cosmos.Table. Установится пакет API таблицы Azure Cosmos DB и все зависимые компоненты.

  4. При выполнении всего приложения данные образца вставляются в сущность таблицы и удаляются в конце выполнения. Поэтому вы не увидите вставленные данные, если выполните образец целиком. Тем не менее, чтобы просмотреть данные, вы можете вставить некоторые точки останова. Откройте файл BasicSamples.cs и щелкните правой кнопкой мыши строку 52, нажмите Точка останова и выберите Вставить точку останова. Вставьте еще одну точку останова в строке 55.

    Добавление точки останова

  5. Нажмите клавишу F5 для запуска приложения. В окне консоли отобразится имя новой базы данных таблиц (в этом примере — demoa13b1) в Azure Cosmos DB.

    Выходные данные консоли

    Когда будет достигнута первая точка останова, вернитесь к обозревателю данных на портале Azure. Нажмите кнопку Обновить, разверните пример* таблицы и щелкните Сущности. На вкладке Сущности справа отобразится новая сущность, добавленная для Walter Harp. Обратите внимание, что для новой сущности указан номер телефона 425-555-0101.

    Новая сущность

    Если возникнет ошибка с сообщением о том, что при запуске проекта файл Settings.json не удалось найти, эту ошибку можно устранить, добавив в настройки проекта следующую XML-запись. Щелкните правой кнопкой мыши CosmosTableSamples, выберите "Редактировать CosmosTableSamples.csproj" и добавьте следующий элемент itemGroup.

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. Закройте вкладку Сущности в обозревателе данных.

  7. Нажмите клавишу F5, чтобы приложение выполнялось до следующей точки останова.

    Когда будет достигнута точка останова, снова щелкните Сущности на портале Azure, чтобы открыть вкладку Сущности. Обратите внимание, что номер телефона изменился на 425-555-0105.

  8. Нажмите клавишу F5, чтобы запустить приложение.

    Приложение добавляет сущности для использования в расширенном примере приложения, который API таблицы сейчас не поддерживает. Затем приложение удаляет таблицу, созданную в примере приложения.

  9. Откройте окно консоли и нажмите клавишу ВВОД, чтобы завершить работу приложения.

Просмотр соглашений об уровне обслуживания на портале Azure

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

Чтобы просмотреть метрики и соглашения об уровне обслуживания, сделайте следующее:

  1. Выберите Метрики в меню навигации учетной записи Cosmos DB.

  2. Выберите вкладку, например Задержка, и укажите временной интервал справа. Сравните на диаграмме строки Actual (Фактическое значение) и SLA (Соглашение об уровне обслуживания).

    Набор метрик Azure Cosmos DB

  3. Просмотрите метрики на других вкладках.

Очистка ресурсов

После завершения работы с приложением и учетной записью Azure Cosmos DB можно удалить созданные ресурсы Azure, чтобы избежать дополнительных расходов. Удаление ресурсов:

  1. На панели поиска портала Azure найдите и выберите Группы ресурсов.

  2. Выберите из списка группу ресурсов, созданную для этого краткого руководства.

    Выбор удаляемой группы ресурсов

  3. На странице обзора группы ресурсов выберите Удалить группу ресурсов.

    удаление группы ресурсов.

  4. В следующем окне введите имя группы ресурсов, которую требуется удалить, и щелкните Удалить.

Дальнейшие действия

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