azure
Support formation Microsoft Azure
azure
Support formation Microsoft Azure
Labs 203 | Azure Date Engineer

Lab 12-14 | Utiliser Azure Synapse Link pour Azure Cosmos DB

Gonzague Ducos
Azure Synapse Link pour Azure Cosmos DB est une technologie de traitement analytique transactionnel hybride (HTAP) native du cloud qui vous permet d’exécuter des analytiques en temps quasi réel sur des données opérationnelles stockées dans Azure Cosmos DB à partir d’Azure Synapse Analytique.
Cet exercice devrait durer environ 35 minutes.

Avant de commencer

Vous aurez besoin d’un
abonnement Azure
⁠
dans lequel vous disposez d’un accès de niveau administratif.

Approvisionner des ressources Azure

Pour explorer Azure Synapse Link pour Azure Cosmos DB, vous aurez besoin d’un espace de travail Azure Synapse Analytique et d’un compte Azure Cosmos DB. Dans cet exercice, vous allez utiliser une combinaison d’un script PowerShell et d’un modèle ARM pour provisionner ces ressources dans votre abonnement Azure.
Connectez-vous au
portail Azure
⁠
à l’adresse https://portal.azure.com.
Utilisez le bouton [>_] à droite de la barre de recherche en haut de la page pour créer un Cloud Shell dans le portail Azure, en sélectionnant un environnement PowerShell et en créant un stockage si vous y êtes invité. Cloud Shell fournit une interface de ligne de commande dans un volet situé au bas du portail Azure, comme illustré ici : ​
⁠
​Remarque : Si vous avez déjà créé un Cloud Shell qui utilise un environnement Bash, utilisez le menu déroulant en haut à gauche du volet Cloud Shell pour le remplacer par PowerShell.
Notez que vous pouvez redimensionner la coque du nuage en faisant glisser la barre de séparation en haut du volet ou en utilisant les icônes —, ◻ et X en haut à droite du volet pour réduire, agrandir et fermer le volet. Pour plus d’informations sur l’utilisation d’Azure Cloud Shell, consultez la
documentation Azure Cloud Shell
⁠
.
Dans le volet PowerShell, entrez les commandes suivantes pour cloner ce référentiel :
rm -r dp-203 -f
git clone https://github.com/MicrosoftLearning/dp-203-azure-data-engineer dp-203
Une fois le référentiel cloné, entrez les commandes suivantes pour accéder au dossier de cet exercice et exécutez le script setup.ps1 qu’il contient :
cd dp-203/Allfiles/labs/14
./setup.ps1
Si vous y êtes invité, choisissez l’abonnement que vous souhaitez utiliser (cela ne se produira que si vous avez accès à plusieurs abonnements Azure).
Lorsque vous y êtes invité, entrez un mot de passe approprié à définir pour votre pool SQL Azure Synapse. ​Remarque : N’oubliez pas ce mot de passe !
Attendez que le script soit terminé - cela prend généralement environ 10 minutes, mais dans certains cas, cela peut prendre plus de temps. Pendant que vous attendez, consultez l’article
Qu’est-ce qu’Azure Synapse Link pour Azure Cosmos DB ?
⁠
dans la documentation Azure Synapse Analytique.

Configurer Synapse Link dans Azure Cosmos DB

Avant de pouvoir utiliser Synapse Link pour Azure Cosmos DB, vous devez l’activer dans votre compte Azure Cosmos DB et configurer un conteneur en tant que magasin analytique.

Activer la fonctionnalité Synapse Link dans votre compte Cosmos DB

Dans le
portail Azure
⁠
, accédez au groupe de ressources dp203-xxxxxxx créé par le script d’installation et identifiez votre compte CosmosDB cosmos xxxxxxxx. ​Remarque : Dans certains cas, le script peut avoir tenté de créer des comptes Cosmos DB dans plusieurs régions, de sorte qu’il peut y avoir un ou plusieurs comptes dans un état de suppression. Le compte actif doit être celui avec le plus grand nombre à la fin de son nom - par exemple cosmosxxxxxxx3.
Ouvrez votre compte Azure Cosmos DB, puis sélectionnez la page Explorateur de données sur le côté gauche de son panneau. ​Si une boîte de dialogue Bienvenue s’affiche, fermez-la
En haut de la page Explorateur de données, utilisez le bouton Activer Azure Synapse Link pour activer Synapse Link. ​
⁠
⁠
Sur le côté gauche de la page, dans la section Intégrations, sélectionnez la page Lien Azure Synapse et vérifiez que l’état du compte est Activé.

Création d’un conteneur de magasin analytique

Revenez à la page Explorateur de données et utilisez le nouveau bouton (ou la vignette) Conteneur pour créer un conteneur avec les paramètres suivants :
ID de base de données : (Créer) AdventureWorks
Partage du débit entre les conteneurs : Nonsélectionné
Identifiant du conteneur : Ventes
Clé de partition : /customerid
Débit de conteneur (mise à l’échelle automatique) : mise à l’échelle automatique
Conteneur Max RU/s : 4000
Magasin analytique : Sur ​Remarque : Dans ce scénario, customerid est utilisé pour la clé de partition, car il est susceptible d’être utilisé dans de nombreuses requêtes pour récupérer des informations sur les clients et les commandes client dans une application hypothétique, il a une cardinalité relativement élevée (nombre de valeurs uniques), de sorte qu’il permettra au conteneur d’évoluer à mesure que le nombre de clients et de commandes client augmente. L’utilisation de la mise à l’échelle automatique et la définition de la valeur maximale sur 4000 RU/s sont appropriées pour une nouvelle application avec des volumes de requêtes initialement faibles. Une valeur maximale de 4000 RU/s permet au conteneur d’évoluer automatiquement entre cette valeur et jusqu’à 10 % de cette valeur maximale (400 RU/s) lorsqu’il n’est pas nécessaire.
Une fois le conteneur créé, dans la page Explorateur de données, développez la base de données AdventureWorks et son dossier Sales ; , puis sélectionnez le dossier Éléments. ​
⁠
⁠
Utilisez le bouton Nouvel article pour créer un nouvel article client basé sur le JSON suivant. Enregistrez ensuite le nouvel élément (des champs de métadonnées supplémentaires seront ajoutés lorsque vous enregistrerez l’élément).
{
"id": "SO43701",
"orderdate": "2019-07-01",
"customerid": 123,
"customerdetails": {
"customername": "Christy Zhu",
"customeremail": "christy12@adventure-works.com"
},
"product": "Mountain-100 Silver, 44",
"quantity": 1,
"price": 3399.99
}

Ajoutez un deuxième élément avec le JSON suivant :
{
"id": "SO43704",
"orderdate": "2019-07-01",
"customerid": 124,
"customerdetails": {
"customername": "Julio Ruiz",
"customeremail": "julio1@adventure-works.com"
},
"product": "Mountain-100 Black, 48",
"quantity": 1,
"price": 3374.99
}

Ajoutez un troisième élément avec le JSON suivant :
{
"id": "SO43707",
"orderdate": "2019-07-02",
"customerid": 125,
"customerdetails": {
"customername": "Emma Brown",
"customeremail": "emma3@adventure-works.com"
},
"product": "Road-150 Red, 48",
"quantity": 1,
"price": 3578.27
}

Remarque : En réalité, le magasin analytique contiendrait un volume beaucoup plus important de données, écrites dans le magasin par une application. Ces quelques éléments suffiront à démontrer le principe dans cet exercice.

Configurer Synapse Link dans Azure Synapse Analytique

Maintenant que vous avez préparé votre compte Azure Cosmos DB, vous pouvez configurer le lien Azure Synapse pour Azure Cosmos DB dans votre espace de travail Azure Synapse Analytique.
Dans le portail Azure, fermez le panneau de votre compte Cosmos DB s’il est toujours ouvert, puis revenez au groupe de ressources dp203-xxxxxxx.
Ouvrez l’espace de travail Synapsexxxxxxx Synapse, et sur sa page Vue d’ensemble, dans la carte Ouvrir Synapse Studio, sélectionnez Ouvrir pour ouvrir Synapse Studio dans un nouvel onglet du navigateur ; Connectez-vous si vous y êtes invité.
Sur le côté gauche de Synapse Studio, utilisez l’icône ›› pour développer le menu - cela révèle les différentes pages de Synapse Studio.
Sur la page Données, affichez l’onglet Lié. Votre espace de travail doit déjà inclure un lien vers votre compte de stockage Azure Data Lake Storage Gen2, mais aucun lien vers votre compte Cosmos DB.
Dans le menu +, sélectionnez Se connecter à des données externes, puis Azure Cosmos DB pour NoSQL. ​
⁠
⁠
Poursuivez et créez une connexion Cosmos DB avec les paramètres suivants :
Nom : AdventureWorks
Description : base de données Cosmos DB d’AdventureWorks
Se connecter via le runtime d’intégration : AutoResolveIntegrationRuntime
Type d’authentification : Clé de compte
Chaîne de connexion : sélectionnée
Méthode de sélection du compte : À partir de l’abonnement
Abonnement Azure : sélectionnez votre abonnement Azure
Nom du compte Azure Cosmos DB : sélectionnez votre compte cosmosxxxxxxx
Nom de la base de données : AdventureWorks
Après avoir créé la connexion, utilisez le bouton ↻ en haut à droite de la page Données pour actualiser la vue jusqu’à ce qu’une catégorie Azure Cosmos DB soit répertoriée dans le volet Lié.
Développez la catégorie Azure Cosmos DB pour voir la connexion AdventureWorks que vous avez créée et le conteneur Sales qu’elle contient. ​
⁠
⁠

Interroger Azure Cosmos DB à partir d’Azure Synapse Analytique

Vous êtes maintenant prêt à interroger votre base de données Cosmos DB à partir d’Azure Synapse Analytique.

Interroger Azure Cosmos DB à partir d’un pool Spark

Dans le volet Données, sélectionnez le conteneur Sales, puis dans son menu, sélectionnez Nouveau bloc-notes > Charger dans DataFrame.
Dans le nouvel onglet Notebook 1 qui s’ouvre, dans la liste Attacher à, sélectionnez votre pool Spark (sparkxxxxxxx). Utilisez ensuite le bouton ▷ Exécuter tout pour exécuter toutes les cellules du carnet (il n’y en a actuellement qu’une seule !).
Étant donné que c’est la première fois que vous exécutez du code Spark dans cette session, le pool Spark doit être démarré. Cela signifie que la première exécution de la session peut prendre quelques minutes. Les exécutions suivantes seront plus rapides.
Pendant que vous attendez l’initialisation de la session Spark, examinez le code qui a été généré (vous pouvez utiliser le bouton Propriétés, qui ressemble à 🗏*, à l’extrémité droite de la barre d’outils pour fermer le volet Propriétés afin que vous puissiez voir le code plus clairement). Le code doit ressembler à ceci :
# Read from Cosmos DB analytical store into a Spark DataFrame and display 10 rows from the DataFrame
# To select a preferred list of regions in a multi-region Cosmos DB account, add .option("spark.cosmos.preferredRegions", "<Region1>,<Region2>")

df = spark.read\
.format("cosmos.olap")\
.option("spark.synapse.linkedService", "AdventureWorks")\
.option("spark.cosmos.container", "Sales")\
.load()

display(df.limit(10))
Une fois l’exécution du code terminée, puis examinez la sortie sous la cellule dans le bloc-notes. Les résultats devraient comprendre trois enregistrements ; un pour chacun des éléments que vous avez ajoutés à la base de données Cosmos DB. Chaque enregistrement comprend les champs que vous avez saisis lors de la création des éléments, ainsi que certains des champs de métadonnées qui ont été générés automatiquement.
Sous les résultats de la cellule précédente, utilisez l’icône Code + pour ajouter une nouvelle cellule au bloc-notes, puis entrez le code suivant dans celle-ci :
customer_df = df.select("customerid", "customerdetails")
display(customer_df)
Utilisez l’icône ▷ à gauche de la cellule pour l’exécuter et afficher les résultats ; qui devrait être similaire à ceci :
customerid
customerdetails
124
« {"customername » : « Julio Ruiz »,"customeremail » : « julio1@adventure-works.com"} »
125
« {"customername » : « Emma Brown »,"customeremail » : « emma3@adventure-works.com"} »
123
« {"customername » : « Christy Zhu »,"customeremail » : « christy12@adventure-works.com"} »
There are no rows in this table
⁠
Cette requête a créé une nouvelle trame de données contenant uniquement les colonnes customerid et customerdetails. Notez que la colonne customerdetails contient la structure JSON des données imbriquées dans l’élément source. Dans le tableau des résultats qui s’affiche, vous pouvez utiliser l’icône ► en regard de la valeur JSON pour la développer et voir les champs individuels qu’elle contient.
Ajoutez une autre nouvelle cellule de code et entrez le code suivant :
customerdetails_df = df.select("customerid", "customerdetails.*")
display(customerdetails_df)
Exécutez la cellule et examinez les résultats, qui doivent inclure le nom du client et l’adresse e-mail du client de la valeur customerdetails sous forme de colonnes :
customerid
customername
customeremail
124
Julio Ruiz
⁠
julio1@adventure-works.com
⁠
⁠
125
Emma Brown
⁠
emma3@adventure-works.com
⁠
⁠
123
Christy Zhu
⁠
christy12@adventure-works.com
⁠
⁠
There are no rows in this table
⁠
Spark vous permet d’exécuter du code de manipulation de données complexe pour restructurer et explorer les données de Cosmos DB. Dans ce cas, le langage PySpark vous permet de naviguer dans la hiérarchie des propriétés JSON pour récupérer les champs enfants du champ customerdetails.
Ajoutez une autre nouvelle cellule de code et entrez le code suivant :
%%sql

-- Create a logical database in the Spark metastore
CREATE DATABASE salesdb;

USE salesdb;

-- Create a table from the Cosmos DB container
CREATE TABLE salesorders using cosmos.olap options (
spark.synapse.linkedService 'AdventureWorks',
spark.cosmos.container 'Sales'
);

-- Query the table
SELECT *
FROM salesorders;

Exécutez la nouvelle cellule pour créer une base de données contenant une table qui inclut des données du magasin analytique Cosmos DB.
Ajoutez une autre nouvelle cellule de code, puis entrez et exécutez le code suivant :
%%sql

SELECT id, orderdate, customerdetails.customername, product
FROM salesorders
ORDER BY id;

Les résultats de cette requête doivent ressembler à ceci :
id
orderdate
customername
product
SO43701
2019-07-01
Christy Zhu
Mountain-100 Silver, 44
SO43704
2019-07-01
Julio Ruiz
Mountain-100 Black, 48
SO43707
2019-07-02
Emma Brown
Road-150 Red, 48
There are no rows in this table
⁠
Notez que lors de l’utilisation de Spark SQL, vous pouvez récupérer les propriétés nommées d’une structure JSON sous forme de colonnes.
Gardez l’onglet Carnet 1 ouvert, vous y reviendrez plus tard.

Interroger Azure Cosmos DB à partir d’un pool SQL serverless

Dans le volet Données, sélectionnez le conteneur Sales, puis dans son menu ..., sélectionnez Nouveau script SQL > Sélectionner les 100 premières lignes.
Dans l’onglet Script SQL 1 qui s’ouvre, masquez le volet Propriétés et affichez le code qui a été généré, qui doit ressembler à ceci :
IF (NOT EXISTS(SELECT * FROM sys.credentials WHERE name = 'cosmosxxxxxxxx'))
THROW 50000, 'As a prerequisite, create a credential with Azure Cosmos DB key in SECRET option:
CREATE CREDENTIAL [cosmosxxxxxxxx]
WITH IDENTITY = ''SHARED ACCESS SIGNATURE'', SECRET = ''<Enter your Azure Cosmos DB key here>''', 0
GO

SELECT TOP 100 *
FROM OPENROWSET(​PROVIDER = 'CosmosDB',
CONNECTION = 'Account=cosmosxxxxxxxx;Database=AdventureWorks',
OBJECT = 'Sales',
SERVER_CREDENTIAL = 'cosmosxxxxxxxx'
) AS [Sales]

Le pool SQL nécessite des informations d’identification à utiliser lors de l’accès à Cosmos DB, qui sont basées sur une clé d’autorisation pour votre compte Cosmos DB. Le script comprend une initiale IF (NOT EXISTS(... qui vérifie ces informations d’identification et génère une erreur si elles n’existent pas.
Remplacez le IF (NOT EXISTS(... dans le script avec le code suivant pour créer des informations d’identification, en remplaçant cosmosxxxxxxxx par le nom de votre compte Cosmos DB :
CREATE CREDENTIAL [cosmosxxxxxxxx]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
SECRET = '<Enter your Azure Cosmos DB key here>'
GO

L’ensemble du script doit maintenant ressembler à ce qui suit :
CREATE CREDENTIAL [cosmosxxxxxxxx]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
SECRET = '<Enter your Azure Cosmos DB key here>'
GO

SELECT TOP 100 *
FROM OPENROWSET(​PROVIDER = 'CosmosDB',
CONNECTION = 'Account=cosmosxxxxxxxx;Database=AdventureWorks',
OBJECT = 'Sales',
SERVER_CREDENTIAL = 'cosmosxxxxxxxx'
) AS [Sales]

Basculez vers l’onglet du navigateur contenant le portail Azure (ou ouvrez un nouvel onglet et connectez-vous au portail Azure à
l’https://portal.azure.com
⁠
). Ensuite, dans le groupe de ressources dp203-xxxxxxx, ouvrez votre compte Azure Cosmosxxxxxxxx.
Dans le volet de gauche, dans la section Paramètres, sélectionnez la page Clés. Copiez ensuite la valeur de la clé primaire dans le presse-papiers.
Revenez à l’onglet du navigateur contenant le script SQL dans Azure Synapse Studio et collez la clé dans le code en remplaçant l’espace réservé <Entrez votre clé Azure Cosmos DB ici> afin que le script ressemble à ceci :
CREATE CREDENTIAL [cosmosxxxxxxxx]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
SECRET = '1a2b3c....................................=='
GO
Avant de commencer
Approvisionner des ressources Azure
Configurer Synapse Link dans Azure Cosmos DB
Activer la fonctionnalité Synapse Link dans votre compte Cosmos DB
Création d’un conteneur de magasin analytique
Configurer Synapse Link dans Azure Synapse Analytique
Interroger Azure Cosmos DB à partir d’Azure Synapse Analytique
Interroger Azure Cosmos DB à partir d’un pool Spark
Interroger Azure Cosmos DB à partir d’un pool SQL serverless
Vérifier que les modifications de données dans Cosmos DB sont répercutées dans Synapse
Supprimer des ressources Azure
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.