Copier des données de ou vers Azure Cosmos DB pour MongoDB à l’aide d’Azure Data Factory ou de Synapse Analytics

Article
01/05/2024

S’APPLIQUE À : Azure Data Factory Azure Synapse Analytics

Conseil

Essayez Data Factory dans Microsoft Fabric, une solution d’analyse tout-en-un pour les entreprises. Microsoft Fabric couvre tous les aspects, du déplacement des données à la science des données, en passant par l’analyse en temps réel, l’aide à la décision et la création de rapports. Découvrez comment démarrer un nouvel essai gratuitement !

Cet article décrit comment utiliser l’activité de copie dans les pipelines Azure Data Factory et Synapse Analytics pour copier des données de et vers Azure Cosmos DB pour MongoDB. Il s’appuie sur l’article Activité de copie, qui présente une vue d’ensemble de cette activité.

Notes

Ce connecteur prend uniquement en charge la copie de données vers/depuis Azure Cosmos DB pour MongoDB. Pour Azure Cosmos DB for NoSQL et référez-vous le connecteur Azure Cosmos DB for NoSQL. Les autres types d’API ne sont actuellement pas pris en charge.

Fonctionnalités prises en charge

Ce connecteur pour MongoDB d’Azure Cosmos DB est pris en charge pour les fonctionnalités suivantes :

Fonctionnalités prises en charge	IR	Point de terminaison privé managé
Activité de copie (source/récepteur)		✓

① Runtime d’intégration Azure ② Runtime d’intégration auto-hébergé

Vous pouvez copier des données d’Azure Cosmos DB pour MongoDB vers toute banque de données réceptrice prise en charge, ou copier des données de toute banque de données source prise en charge vers Azure Cosmos DB pour MongoDB. Pour obtenir la liste des magasins de données pris en charge en tant que sources et récepteurs pour l’activité de copie, consultez Magasins de données et formats pris en charge.

Vous pouvez utiliser le connecteur d’Azure Cosmos DB pour MongoDB pour :

Copier des données depuis et vers Azure Cosmos DB for MongoDB.
Écrire dans Azure Cosmos DB comme insert ou upsert.
Importer et exporter des documents JSON en l’état, ou copier des données depuis ou vers un jeu de données tabulaire. Les exemples incluent une base de données SQL et un fichier CSV. Pour copier des documents en l'état depuis ou vers des fichiers JSON ou une autre collection Azure Cosmos DB, consultez Importer ou exporter des documents JSON.

Bien démarrer

Pour effectuer l’activité Copie avec un pipeline, vous pouvez vous servir de l’un des outils ou kits SDK suivants :

Créer un service lié Azure Cosmos DB pour MongoDB à l’aide de l’interface utilisateur

Suivez les étapes suivantes pour créer un service lié à Azure Cosmos DB pour MongoDB dans l’interface utilisateur du portail Azure.

Accédez à l’onglet Gérer dans votre espace de travail Azure Data Factory ou Synapse, sélectionnez Services liés, puis cliquez sur Nouveau :
- Azure Data Factory.
- Azure Synapse
Recherchez Azure Cosmos DB for MongoDB et sélectionnez ce connecteur.
Configurez les informations du service, testez la connexion et créez le nouveau service lié.

Informations de configuration des connecteurs

Les sections suivantes fournissent des informations sur les propriétés utilisées pour définir les entités Data Factory spécifiques d’Azure Cosmos DB for MongoDB.

Propriétés du service lié

Les propriétés prises en charge pour le service lié à Azure Cosmos DB pour MongoDB sont les suivantes :

Propriété	Description	Obligatoire
type	La propriété type doit être définie sur CosmosDbMongoDbApi.	Oui
connectionString	Spécifiez la chaîne de connexion pour Azure Cosmos DB for MongoDB. Vous pouvez la trouver sur le portail Microsoft Azure -> votre panneau Azure Cosmos DB -> chaîne de connexion primaire ou secondaire. Pour la version de serveur 3.2, le modèle de chaîne est `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb`. Pour les versions de serveur 3.6+, le modèle de chaîne est `mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.mongo.cosmos.azure.com:10255/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<cosmosdb-name>@`. Vous pouvez également définir un mot de passe dans Azure Key Vault et extraire la configuration `password` de la chaîne de connexion. Pour plus d’informations, consultez la section Stocker des informations d’identification dans Azure Key Vault.	Oui
database	Nom de la base de données à laquelle vous souhaitez accéder.	Oui
isServerVersionAbove32	Spécifiez si la version du serveur est supérieure à 3.2. Les valeurs autorisées sont true et false (par défaut). Cela permet de déterminer le pilote à utiliser dans le service.	Oui
connectVia	Runtime d’intégration à utiliser pour la connexion au magasin de données. Vous pouvez utiliser Azure Integration Runtime ou un runtime d’intégration auto-hébergé si votre banque de données se trouve sur un réseau privé. Si cette propriété n’est pas spécifiée, Azure Integration Runtime par défaut est utilisé.	Non

Exemple

{
    "name": "CosmosDbMongoDBAPILinkedService",
    "properties": {
        "type": "CosmosDbMongoDbApi",
        "typeProperties": {
            "connectionString": "mongodb://<cosmosdb-name>:<password>@<cosmosdb-name>.documents.azure.com:10255/?ssl=true&replicaSet=globaldb",
            "database": "myDatabase",
            "isServerVersionAbove32": "false"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Propriétés du jeu de données

Pour obtenir la liste complète des sections et propriétés disponibles pour la définition de jeux de données, consultez Jeux de données et services liés. Les propriétés prises en charge pour le jeu de données d’Azure Cosmos DB pour MongoDB sont les suivantes :

Propriété	Description	Obligatoire
type	La propriété type du jeu de données doit être définie sur CosmosDbMongoDbApiCollection.	Oui
collectionName	Nom de la collection Azure Cosmos DB.	Oui

Exemple

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

Propriétés de l’activité de copie

Cette section fournit la liste des propriétés prises en charge par Azure Cosmos DB pour MongoDB en tant que source et récepteur.

Pour obtenir la liste complète des sections et des propriétés permettant de définir des activités, consultez Pipelines.

Azure Cosmos DB for MongoDB comme source

Les propriétés prises en charge dans la section source de l’activité de copie sont les suivantes :

Propriété	Description	Obligatoire
type	La propriété type de la source d’activité de copie doit être définie sur CosmosDbMongoDbApiSource.	Oui
filter	Spécifie le filtre de sélection à l’aide d’opérateurs de requête. Pour retourner tous les documents dans une collection, omettez ce paramètre ou passez un document vide ({}).	Non
cursorMethods.project	Spécifie les champs à retourner dans les documents pour la projection. Pour retourner tous les champs dans les documents correspondants, omettez ce paramètre.	Non
cursorMethods.sort	Spécifie l’ordre dans lequel la requête retourne les documents correspondants. Voir cursor.sort().	Non
cursorMethods.limit	Spécifie le nombre maximal de documents retournés par le serveur. Voir cursor.limit().	Non
cursorMethods.skip	Spécifie le nombre de documents à ignorer, et à partir de quel endroit MongoDB commence à retourner des résultats. Voir cursor.skip().	Non
batchSize	Spécifie le nombre de documents à retourner dans chaque lot de la réponse renvoyée par l’instance MongoDB. Dans la plupart des cas, la modification de la taille de lot n’affectera pas l’utilisateur ou l’application. Azure Cosmos DB limite la taille de chaque lot à 40 Mo, qui est la somme de la taille batchSize du nombre de documents. Par conséquent, diminuez cette valeur si la taille de votre document est trop grande.	Non (la valeur par défaut est 100)

Conseil

ADF prend en charge la consommation de document BSON en mode Strict. Vérifiez que votre requête de filtre est en mode Strict plutôt qu’en mode Shell. Vous trouverez une description plus détaillée dans le manuel MongoDB.

Exemple

"activities":[
    {
        "name": "CopyFromCosmosDBMongoDBAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Azure Cosmos DB for MongoDB input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbMongoDbApiSource",
                "filter": "{datetimeData: {$gte: ISODate(\"2018-12-11T00:00:00.000Z\"),$lt: ISODate(\"2018-12-12T00:00:00.000Z\")}, _id: ObjectId(\"5acd7c3d0000000000000000\") }",
                "cursorMethods": {
                    "project": "{ _id : 1, name : 1, age: 1, datetimeData: 1 }",
                    "sort": "{ age : 1 }",
                    "skip": 3,
                    "limit": 3
                }
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Azure Cosmos DB for MongoDB comme lien

Les propriétés suivantes sont prises en charge dans la section sink de l’activité de copie :

Propriété	Description	Obligatoire
type	La propriété type du récepteur d’activité de copie doit être définie sur CosmosDbMongoDbApiSink.	Oui
writeBehavior	Décrit comment écrire des données dans Azure Cosmos DB. Les valeurs autorisées sont insert et upsert. Le comportement de la valeur upsert consiste à remplacer le document si un document portant le même `_id` existe déjà ; sinon, le document est inséré. Remarque : le service génère automatiquement un `_id` pour un document si aucun `_id` n’est spécifié ni dans le document d’origine ni par le mappage de colonnes. Cela signifie que vous devez vérifier que votre document comporte un ID afin qu’upsert fonctionne comme prévu.	Non (la valeur par défaut est insert)
writeBatchSize	La propriété writeBatchSize contrôle la taille des documents à écrire dans chaque lot. Vous pouvez essayer d’augmenter la valeur de writeBatchSize pour améliorer les performances et diminuer la valeur si la taille de votre document est grande.	Non (la valeur par défaut est 10 000)
writeBatchTimeout	Temps d’attente pour que l’opération d’insertion par lot soit terminée avant d’expirer. La valeur autorisée est timespan.	Non (la valeur par défaut est 00:30:00 – 30 minutes)

Conseil

Pour importer des documents JSON en l’état, voir la section Importer ou exporter des documents JSON. Pour copier à partir de données sous forme tabulaire, voir Mappage de schéma.

Exemple

"activities":[
    {
        "name": "CopyToCosmosDBMongoDBAPI",
        "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": "CosmosDbMongoDbApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

Importer et exporter des documents JSON

À l’aide de ce connecteur Azure Cosmos DB, vous pouvez facilement :

Copier des documents entre deux collections Azure Cosmos DB en l’état.
Importer des documents JSON de différentes sources dans Azure Cosmos DB, notamment depuis MongoDB, le Stockage Blob Azure, Azure Data Lake Store et d’autres magasins de données basés sur des fichiers pris en charge par le service.
Exporter des documents JSON d’une collection Azure Cosmos DB vers différentes banques basées sur des fichiers.

Pour obtenir une copie indépendante du schéma :

Lors de l’utilisation de l’outil de copie de données, sélectionnez l’option Exporter en l’état dans des fichiers JSON ou une collection Azure Cosmos DB.
Lors de l’utilisation de la création d’activité, choisissez le format JSON avec le magasin de fichiers correspondant à la source ou au récepteur.

Mappage de schéma

Pour copier des données d’Azure Cosmos DB pour MongoDB vers un récepteur tabulaire ou inversement, consultez Mappage de schéma.

Plus spécifiquement, pour l’écriture dans Azure Cosmos DB, pour vous assurer de remplir Azure Cosmos DB avec l’ID d’objet approprié à partir de vos données sources (par exemple, vous avez une colonne « id » dans la table de base de données SQL, et souhaitez utiliser la valeur de celle-ci en tant qu’ID de document dans MongoDB pour insérer/fusionner), vous devez définir le mappage de schéma approprié en fonction de la définition du mode strict MongoDB (_id.$oid) comme suit :

Map ID in MongoDB sink

Après exécution de l’activité de copie, sous BSON, ObjectId est généré dans un récepteur :

{
    "_id": ObjectId("592e07800000000000000000")
}

Pour obtenir la liste des magasins de données pris en charge par l'activité Copy en tant que sources et récepteurs, consultez Magasins de données pris en charge.

Copier des données de ou vers Azure Cosmos DB pour MongoDB à l’aide d’Azure Data Factory ou de Synapse Analytics

Fonctionnalités prises en charge

Bien démarrer

Créer un service lié Azure Cosmos DB pour MongoDB à l’aide de l’interface utilisateur

Informations de configuration des connecteurs

Propriétés du service lié

Propriétés du jeu de données

Propriétés de l’activité de copie

Azure Cosmos DB for MongoDB comme source

Azure Cosmos DB for MongoDB comme lien

Importer et exporter des documents JSON

Mappage de schéma

Contenu connexe

Ressources supplémentaires