Краткое руководство: как использовать конструктор API для данных с NoSQL

В этом кратком руководстве описано, как создать конечные точки GraphQL для локального эмулятора Azure Cosmos DB для NoSQL с помощью построителя API данных (DAB).

Необходимые условия

• Docker
• .NET 8

Установка интерфейса командной строки построителя API данных

Установите пакет Microsoft.DataApiBuilder из NuGet в качестве инструмента .NET.

1. Используйте dotnet tool install для установки последней версии Microsoft.DataApiBuilder, используя аргумент --global.

   dotnet tool install --global Microsoft.DataApiBuilder
   

   Замечание

   Если пакет уже установлен, вместо этого обновите пакет, используя dotnet tool update.

   dotnet tool update --global Microsoft.DataApiBuilder
   

2. Убедитесь, что средство установлено с dotnet tool list помощью аргумента --global .

   dotnet tool list --global
   

Извлечение образа эмулятора

Скачайте образ эмулятора Azure Cosmos DB для NoSQL. Это может занять несколько минут, так как образ эмулятора большой.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Запуск эмулятора

Запустите эмулятор Cosmos DB в Docker. Этот AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE параметр необходим, чтобы эмулятор объявлял 127.0.0.1 свои сетевые конечные точки, что делает их доступными на хост-компьютере.

docker run --name dab-cosmos --publish 8081:8081 --publish 10250-10255:10250-10255 --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 --detach mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

Установка сертификата эмулятора

Эмулятор Cosmos DB использует самозаверяющий SSL-сертификат. Скачайте и доверяйте этому сертификату, чтобы Data API Builder смог подключиться к эмулятору.

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/emulatorcert.crt

curl.exe -k https://localhost:8081/_explorer/emulator.pem -o "$env:USERPROFILE\emulatorcert.crt"
Import-Certificate -CertStoreLocation "Cert:\CurrentUser\Root" -FilePath "$env:USERPROFILE\emulatorcert.crt"

Создайте базу данных и первоначальные данные

Используйте встроенный обозреватель данных эмулятора для создания базы данных, контейнера и примеров элементов. Никаких дополнительных средств не требуется— обозреватель данных запускается в браузере в рамках эмулятора.

1. Откройте обозреватель данных по адресу https://localhost:8081/_explorer/index.html.

2. Выберите новую базу данных. Введите todos в качестве идентификатора базы данных и нажмите кнопку "ОК".

3. Разверните базу данных todos, выберите меню с многоточием (...) и выберите Новый контейнер. Введите todos в качестве идентификатора контейнера и /id в качестве ключа секции, а затем нажмите кнопку "ОК".

4. Разверните контейнер тодос и выберите "Элементы". Затем выберите новый элемент, замените JSON по умолчанию следующим содержимым и нажмите кнопку "Сохранить". Повторите для каждого элемента.

   Элемент 1.

   {
     "id": "1",
     "title": "Walk the dog",
     "completed": false
   }
   

   Элемент 2.

   {
     "id": "2",
     "title": "Feed the fish",
     "completed": false
   }
   

   Элемент 3.

   {
     "id": "3",
     "title": "Comb the cat",
     "completed": true
   }
   

Создание файла схемы GraphQL

Для Azure Cosmos DB для NoSQL требуется файл схемы GraphQL. Создайте файл с именем schema.gql со следующим содержимым.

type Todo @model {
  id: ID!
  title: String!
  completed: Boolean!
}

Настройка построителя API данных

1. Инициализация конфигурации с помощью строки подключения по умолчанию эмулятора.

   dab init --database-type "cosmosdb_nosql" --host-mode "Development" --cosmosdb_nosql-database todos --graphql-schema schema.gql --connection-string "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
   

2. Добавьте сущность Todo .

   dab add Todo --source "todos" --permissions "anonymous:*"
   

Теперь файл dab-config.json должен выглядеть примерно так:

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "connection-string": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
    "options": {
      "database": "todos",
      "schema": "schema.gql"
    }
  },
  "runtime": {
    "graphql": {
      "enabled": true
    },
    "host": {
      "mode": "development"
    }
  },
  "entities": {
    "Todo": {
      "source": {
        "object": "todos",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ]
    }
  }
}

Запуск API

Используйте dab start для запуска инструмента и создания конечных точек API для вашей сущности.

dab start

Выходные данные должны содержать адрес запущенного API.

      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>

Проверка API

1. Откройте браузер и перейдите к конечной точке GraphQL.

   http://localhost:5000/graphql
   

   В режиме разработки этот URL-адрес открывает интегрированную среду разработки Nitro GraphQL.

2. Создайте новый документ и выполните следующий запрос, чтобы получить все элементы todo.

   query {
     todos {
       items {
         id
         title
         completed
       }
     }
   }
   

3. Ответ должен содержать все три элемента todo.

   {
     "data": {
       "todos": {
         "items": [
           { "id": "1", "title": "Walk the dog", "completed": false },
           { "id": "2", "title": "Feed the fish", "completed": false },
           { "id": "3", "title": "Comb the cat", "completed": true }
         ]
       }
     }
   }
   

Очистка

Остановите и удалите контейнер Docker после завершения.

docker stop dab-cosmos && docker rm dab-cosmos

Следующий шаг

Связанный контент

• Настройте конструктор API данных для Azure Cosmos DB для NoSQL
• Доступность компонентов для построителя API данных