Копирование и преобразование данных в Azure Cosmos DB для NoSQL с помощью Фабрика данных Azure

ОБЛАСТЬ ПРИМЕНЕНИЯ: Фабрика данных Azure Azure Synapse Analytics

В этой статье описывается, как использовать действие копирования в Фабрика данных Azure для копирования данных из Azure Cosmos DB для NoSQL и использования Поток данных для преобразования данных в Azure Cosmos DB для NoSQL. Дополнительные сведения см. в вводных статьях о Фабрике данных Azure и Azure Synapse Analytics.

Поддерживаемые возможности

Этот соединитель Azure Cosmos DB для NoSQL поддерживается для следующих возможностей:

① Среда выполнения интеграции Azure ② Локальная среда выполнения интеграции

Для действие Copy этот соединитель Azure Cosmos DB для NoSQL поддерживает:

• Скопируйте данные из Azure Cosmos DB для NoSQL с помощью ключей, субъекта-службы или управляемых удостоверений для проверки подлинности ресурсов Azure.
• Запись данных в Azure Cosmos DB с помощью операции INSERT или UPSERT.
• Импорт и экспорт документов JSON "как есть" либо копирование данных из набора табличных данных или в него. К примерам можно отнести базу данных SQL и CSV-файл. Сведения о копировании документов "как есть" в JSON-файлы или другую коллекцию Azure Cosmos DB либо из них см. в разделе Импорт и экспорт документов JSON.

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

Get started

Для выполнения действия копирования с конвейером можно использовать один из следующих средств или пакетов SDK:

• Средство копирования данных
• Портал Azure
• Пакет SDK для .NET
• Пакет SDK для Python
• Azure PowerShell
• REST API
• Шаблон Azure Resource Manager

Создание связанной службы для Azure Cosmos DB с помощью пользовательского интерфейса

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

1. Перейдите на вкладку "Управление" в Фабрике данных Azure или рабочей области Synapse и выберите "Связанные службы", затем щелкните "Создать".

   • Фабрика данных Azure
   • Azure Synapse

   

2. Найдите Azure Cosmos DB для NoSQL и выберите соединитель Azure Cosmos DB для NoSQL.

   

3. Настройте сведения о службе, проверьте подключение и создайте связанную службу.

   

Сведения о конфигурации соединителя

В следующих разделах содержатся сведения о свойствах, которые можно использовать для определения сущностей, относящихся к Azure Cosmos DB для NoSQL.

Свойства связанной службы

Соединитель Azure Cosmos DB для NoSQL поддерживает следующие типы проверки подлинности. Дополнительные сведения см. в соответствующих разделах:

• Проверка подлинности ключа
• Проверка подлинности субъекта-службы
• Проверка подлинности с помощью назначенного системой управляемого удостоверения
• Проверка подлинности с помощью назначаемого пользователем управляемого удостоверения

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

Example

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Пример: ключ учетной записи хранения в Azure Key Vault

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;Database=<Database>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Аутентификация субъекта-службы

Чтобы использовать аутентификацию на основе субъекта-службы, выполните следующие действия.

1. Регистрация приложения с помощью платформы удостоверений Майкрософт. Дополнительные сведения см. в кратком руководстве. Регистрация приложения с помощью платформа удостоверений Майкрософт. Запишите эти значения, которые используются для определения связанной службы:

   • Идентификатор приложения
   • ключ приложения.
   • Идентификатор арендатора

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

Приведенные ниже свойства поддерживаются в связанной службе.

Пример: использование проверки подлинности с помощью ключа субъекта-службы

Вы также можете хранить ключ субъекта-службы в Azure Key Vault.

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Пример: использование проверки подлинности с помощью сертификата субъекта-службы

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Проверка подлинности с помощью назначенного системой управляемого удостоверения

Конвейер Фабрики данных или Synapse может быть связан с управляемым удостоверением для ресурсов Azure, назначаемым системой, которое представляет этот экземпляр службы. Вы можете напрямую использовать это управляемое удостоверение для проверки подлинности Azure Cosmos DB, аналогично использованию собственного субъекта-службы. Он позволяет этому назначенному ресурсу получать доступ к данным и копировать их в экземпляр Azure Cosmos DB или из него.

Чтобы использовать управляемые удостоверения, назначаемые системой, для аутентификации ресурсов Azure, выполните следующие действия:

1. Получите сведения об управляемом удостоверении, назначаемом системой, скопировав значение идентификатора объекта управляемого удостоверения, созданного вместе со службой.

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

Приведенные ниже свойства поддерживаются в связанной службе.

Example:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "subscriptionId": "<subscription id>",
            "tenantId": "<tenant id>",
            "resourceGroup": "<resource group>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Проверка подлинности с помощью назначаемого пользователем управляемого удостоверения

Конвейер Фабрики данных или Synapse может быть связан с управляемым удостоверением, назначаемым системой, которое представляет этот экземпляр службы. Вы можете напрямую использовать это управляемое удостоверение для проверки подлинности Azure Cosmos DB, аналогично использованию собственного субъекта-службы. Он позволяет этому назначенному ресурсу получать доступ к данным и копировать их в экземпляр Azure Cosmos DB или из него.

Чтобы использовать управляемые удостоверения, назначаемые пользователем, для аутентификации ресурсов Azure, выполните следующие действия:

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

2. Присвойте одно или несколько управляемых удостоверений, назначаемых пользователем, фабрике данных и создайте учетные данные для каждого подобного удостоверения.

Приведенные ниже свойства поддерживаются в связанной службе.

Example:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "subscriptionId": "<subscription id>",
            "tenantId": "<tenant id>",
            "resourceGroup": "<resource group>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Свойства набора данных

Полный список разделов и свойств, используемых для определения наборов данных, приведен в статье Наборы данных и связанные службы в фабрике данных Azure.

Следующие свойства поддерживаются для набора данных Azure Cosmos DB для NoSQL:

Если вы используете набор данных типа DocumentDbCollection, он по-прежнему поддерживается as-is для обратной совместимости для действия копирования и поиска, он не поддерживается для потока данных. Вам предлагается использовать новую модель в дальнейшем.

Example

{
    "name": "CosmosDbSQLAPIDataset",
    "properties": {
        "type": "CosmosDbSqlApiCollection",
        "linkedServiceName":{
            "referenceName": "<Azure Cosmos DB linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [],
        "typeProperties": {
            "collectionName": "<collection name>"
        }
    }
}

Свойства действия копирования

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

Azure Cosmos DB для NoSQL в качестве источника

Чтобы скопировать данные из Azure Cosmos DB для NoSQL, задайте тип источника в действии копирования в DocumentDbCollectionSource.

В разделе source действия копирования поддерживаются следующие свойства:

Если используется источник типа DocumentDbCollectionSource, он по-прежнему поддерживается as-is для обратной совместимости. Вам предлагается использовать новую модель, которая предоставляет более широкие возможности для копирования данных из Azure Cosmos DB.

Example

"activities":[
    {
        "name": "CopyFromCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cosmos DB for NoSQL input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbSqlApiSource",
                "query": "SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"",
                "preferredRegions": [
                    "East US"
                ]
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

При копировании данных из Azure Cosmos DB, если только вы не хотите экспортировать документы JSON как есть, рекомендуется указать сопоставление в действии копирования. Служба учитывает сопоставление, указанное в действии. Если строка не содержит значения для столбца, для него передается значение null. Если сопоставление не указано, служба определяет схему, используя первую строку данных. Если первая строка не содержит полную схему, после операции копирования некоторые столбцы будут отсутствовать.

Azure Cosmos DB для NoSQL в качестве приемника

Чтобы скопировать данные в Azure Cosmos DB для NoSQL, задайте тип приемника в действии копирования в DocumentDbCollectionSink.

В разделе sink действия копирования поддерживаются следующие свойства:

Если используется источник типа DocumentDbCollectionSink, он по-прежнему поддерживается as-is для обратной совместимости. Вам предлагается использовать новую модель, которая предоставляет более широкие возможности для копирования данных из Azure Cosmos DB.

Example

"activities":[
    {
        "name": "CopyToCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Document DB output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "CosmosDbSqlApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

Сопоставление схем

Чтобы скопировать данные из Azure Cosmos DB в табличный приемник или наоборот, обратитесь к разделу Сопоставление схем.

Свойства потока данных для сопоставления

При преобразовании данных в потоке данных сопоставления можно читать и записывать в коллекции в Azure Cosmos DB. Дополнительные сведения см. в описаниях преобразования источника и преобразования приемника в разделе, посвященном потокам данных для сопоставления.

Преобразование источника

Параметры, относящиеся к Azure Cosmos DB, находятся на вкладке Параметры источника преобразования источника.

Включите системные столбцы: Если значение true, id, _ts, и другие системные столбцы включаются в метаданные потока данных из Azure Cosmos DB. При обновлении коллекций важно включить это, чтобы можно было получить существующий идентификатор строки.

Размер страницы: число документов на страницу результата запроса. Значение по умолчанию — "-1"; в этом случае используется динамический размер страницы на стороне службы (до 1000).

Пропускная способность. Задайте необязательное значение для количества единиц запросов, которые вы хотите применить к коллекции Azure Cosmos DB для каждого выполнения этого потока данных во время операции чтения. Минимальное значение — 400.

Предпочтительные регионы: выберите предпочтительные регионы чтения для этого процесса.

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

Начните с начала: Если значение true, при первом запуске будет выполнена начальная загрузка полных данных моментального снимка, за которой при последующих запусках будет следовать фиксация измененных данных. Если значение равно false, начальная нагрузка будет пропущена при первом выполнении, а затем будут внесены измененные данные в следующих выполнениях. Параметр выравнивается с тем же именем параметра в справочнике по Azure Cosmos DB. Дополнительные сведения см. в канале изменений Azure Cosmos DB.

Преобразование приемника

Параметры, относящиеся к Azure Cosmos DB, находятся на вкладке Параметры преобразования приемника.

Метод обновления. Определяет, какие операции разрешены в назначении базы данных. По умолчанию разрешены только операции вставки. Для выполнения обновления (update), обновления или вставки (upsert) или удаления (delete) строк требуется преобразование alter-row строк, отмеченных для этих действий. Для выполнения обновления (update), обновления или вставки (upsert) или удаления (delete) должен быть установлен ключевой столбец (или столбцы), позволяющий определить строки для изменения.

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

• Нет: с коллекцией не выполняются никакие действия.
• Создать повторно: коллекция будет удалена и создана повторно.

Размер пакета: целое число, представляющее количество объектов, записываемых в коллекцию Azure Cosmos DB в каждом пакете. Обычно для того, чтобы приступить к работе, достаточно размера пакета по умолчанию. При дальнейшей корректировке этого значения учитывайте указанные ниже моменты.

• Azure Cosmos DB ограничивает размер одного запроса на 2 МБ. Формула выглядит так: размер запроса = размер одного документа × размер пакета. Если возникла ошибка с сообщением о том, что размер запроса слишком велик, уменьшите пакет.
• Чем больше размер пакета, тем большей пропускной способности может добиться служба. Однако при этом для рабочей нагрузки необходимо выделить достаточно единиц запросов.

Ключ секции: введите строку, представляющую ключ секции для коллекции. Пример: /movies/title

Пропускная способность. Задайте необязательное значение для количества единиц запросов, которые вы хотите применить к коллекции Azure Cosmos DB для каждого выполнения этого потока данных. Минимальное значение — 400.

Бюджет пропускной способности записи: целое число — число ЕЗ, которые требуется выделить для этой операции записи потока данных из общей пропускной способности, выделенной для коллекции.

Свойства действия поиска

Подробные сведения об этих свойствах см. в разделе Действие поиска.

Импорт и экспорт документов JSON

Этот соединитель Azure Cosmos DB для NoSQL можно использовать с легкостью:

• копировать документы между двумя коллекциями Azure Cosmos DB "как есть".
• импортировать документы JSON из различных источников в Azure Cosmos DB, включая хранилище BLOB-объектов Azure, Azure Data Lake Store и другие файловые хранилища, поддерживаемые службой;
• экспортировать документы JSON из коллекции Azure Cosmos DB в различные файловые хранилища;

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

• При использовании средства копирования данных выберите "Экспорт как есть" в JSON-файлы или коллекцию Azure Cosmos DB.
• При разработке действий выберите формат JSON с соответствующим хранилищем файлов для источника или приемника.

Миграция из реляционной базы данных в Azure Cosmos DB

При миграции из реляционной базы данных, например, с SQL Server в Azure Cosmos DB, процесс копирования может легко сопоставить табличные данные из источника с плоскими документами JSON в Azure Cosmos DB. В некоторых случаях может потребоваться изменить модель данных, чтобы оптимизировать ее для вариантов использования NoSQL в соответствии с моделированием данных в Azure Cosmos DB, например для отмены нормализации данных путем внедрения всех связанных вложенных элементов в один документ JSON. В таком случае обратитесь к этой статье с пошаговым руководством по реализации соответствующей схемы с помощью действия копирования.

Канал изменений Azure Cosmos DB

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

Убедитесь, что название конвейера и имя действия не изменились, чтобы контрольная точка могла быть записана ADF и вы могли получать измененные данные из последнего выполнения автоматически. Если изменить имя конвейера или имя действия, контрольная точка будет сброшена, из-за чего придется начинать работу с начала или получить изменения с текущего момента до следующего выполнения.

При отладке конвейера эта функция работает таким же образом. Имейте в виду, что при обновлении страницы в браузере во время отладки контрольная точка будет сброшена. После того как вы удовлетворены результатом выполнения конвейера в режиме отладки, вы можете приступить к публикации и запуску конвейера. На данный момент, когда вы активируете опубликованный конвейер в первый раз, он автоматически перезапускается с самого начала или получает изменения с этого момента.

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

Кроме того, аналитическое хранилище Azure Cosmos DB теперь поддерживает сбор измененных данных (CDC) для API Azure Cosmos DB для NoSQL и API Azure Cosmos DB для Mongo DB (общедоступная предварительная версия). Аналитическое хранилище Azure Cosmos DB позволяет эффективно использовать непрерывный и добавочный веб-канал измененных (вставленных, обновленных и удаленных) данных из аналитического хранилища.

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

Список хранилищ данных, поддерживаемых действием копирования в качестве источников и приемников, приведен в разделе Поддерживаемые хранилища данных.