Använda tjänstens huvudnamn med Spark 3-anslutningsappen för Azure Cosmos DB för NoSQL

Artikel
08/15/2024

I den här artikeln får du lära dig hur du skapar ett Microsoft Entra-program och tjänstens huvudnamn som kan användas med rollbaserad åtkomstkontroll. Du kan sedan använda tjänstens huvudnamn för att ansluta till ett Azure Cosmos DB för NoSQL-konto från Spark 3.

Förutsättningar

Ett befintligt Azure Cosmos DB för NoSQL-konto.
- Om du har en befintlig Azure-prenumeration skapar du ett nytt konto.
- Ingen Azure-prenumeration? Du kan prova Azure Cosmos DB kostnadsfritt utan kreditkort.
En befintlig Azure Databricks-arbetsyta.
Registrerat Microsoft Entra-program och tjänstens huvudnamn.
- Om du inte har ett huvudnamn och program för tjänsten registrerar du ett program med hjälp av Azure Portal.

Skapa en hemlighet och registrera autentiseringsuppgifter

I det här avsnittet skapar du en klienthemlighet och registrerar värdet för användning senare.

Öppna Azure Portal.
Gå till ditt befintliga Microsoft Entra-program.
Gå till sidan Certifikat och hemligheter . Skapa sedan en ny hemlighet. Spara värdet Klienthemlighet som ska användas senare i den här artikeln.
Gå till sidan Översikt . Leta upp och registrera värdena för program-ID (klient-) ID, objekt-ID och katalog-ID (klientorganisation). Du använder även dessa värden senare i den här artikeln.
Gå till ditt befintliga Azure Cosmos DB för NoSQL-konto.
Registrera URI-värdet på sidan Översikt. Registrera även prenumerations-ID och resursgruppsvärden. Du använder dessa värden senare i den här artikeln.

Skapa en definition och en tilldelning

I det här avsnittet skapar du en rolldefinition för Microsoft Entra-ID. Sedan tilldelar du rollen med behörighet att läsa och skriva objekt i containrarna.

Skapa en roll med hjälp az role definition create av kommandot . Skicka in Azure Cosmos DB för NoSQL-kontonamn och resursgrupp, följt av en brödtext av JSON som definierar den anpassade rollen. Rollen är också begränsad till kontonivån med hjälp /av . Se till att du anger ett unikt namn för din roll med hjälp RoleName av egenskapen för begärandetexten.

az cosmosdb sql role definition create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --body '{
        "RoleName": "<role-definition-name>",
        "Type": "CustomRole",
        "AssignableScopes": ["/"],
        "Permissions": [{
            "DataActions": [
                "Microsoft.DocumentDB/databaseAccounts/readMetadata",
                "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
                "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
            ]
        }]
    }'

Visa en lista över rolldefinitionen som du skapade för att hämta dess unika identifierare i JSON-utdata. Registrera värdet för id JSON-utdata.

az cosmosdb sql role definition list \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>"

[
  {
    ...,
    "id": "/subscriptions/<subscription-id>/resourceGroups/<resource-grou-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/sqlRoleDefinitions/<role-definition-id>",
    ...
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ],
        "notDataActions": []
      }
    ],
    ...
  }
]

Använd az cosmosdb sql role assignment create för att skapa en rolltilldelning. Ersätt <aad-principal-id> med objekt-ID :t som du registrerade tidigare i den här artikeln. Ersätt <role-definition-id> också med värdet id som hämtades från att az cosmosdb sql role definition list köra kommandot i ett tidigare steg.
```
az cosmosdb sql role assignment create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --scope "/" \
    --principal-id "<account-name>" \
    --role-definition-id "<role-definition-id>"
```

Använda tjänstens huvudnamn

Nu när du har skapat ett Microsoft Entra-program och tjänstens huvudnamn, skapat en anpassad roll och tilldelat rollen behörigheter till ditt Azure Cosmos DB för NoSQL-konto bör du kunna köra en notebook-fil.

Öppna din Azure Databricks-arbetsyta.
Skapa ett nytt kluster i arbetsytans gränssnitt. Konfigurera klustret med de här inställningarna, minst:

Version Värde

Körningsversion 13.3 LTS (Scala 2.12, Spark 3.4.1)
Använd arbetsytans gränssnitt för att söka efter Maven-paket från Maven Central med ett grupp-ID för com.azure.cosmos.spark. Installera paketet specifikt för Spark 3.4 med ett artefakt-ID som är prefix för azure-cosmos-spark_3-4 klustret.
Skapa slutligen en ny notebook-fil.

Dricks

Som standard är notebook-filen kopplad till det nyligen skapade klustret.

Version	Värde
Körningsversion	`13.3 LTS (Scala 2.12, Spark 3.4.1)`

I notebook-filen anger du konfigurationsinställningar för Azure Cosmos DB Spark-anslutningsappen för NoSQL-kontoslutpunkten, databasnamnet och containernamnet. Använd värdena Prenumerations-ID, Resursgrupp, Program -ID (klient), Katalog -ID (klientorganisation) och Klienthemlighet som registrerats tidigare i den här artikeln.

# Set configuration settings
config = {
  "spark.cosmos.accountEndpoint": "<nosql-account-endpoint>",
  "spark.cosmos.auth.type": "ServicePrincipal",
  "spark.cosmos.account.subscriptionId": "<subscription-id>",
  "spark.cosmos.account.resourceGroupName": "<resource-group-name>",
  "spark.cosmos.account.tenantId": "<entra-tenant-id>",
  "spark.cosmos.auth.aad.clientId": "<entra-app-client-id>",
  "spark.cosmos.auth.aad.clientSecret": "<entra-app-client-secret>",
  "spark.cosmos.database": "<database-name>",
  "spark.cosmos.container": "<container-name>"        
}

// Set configuration settings
val config = Map(
  "spark.cosmos.accountEndpoint" -> "<nosql-account-endpoint>",
  "spark.cosmos.auth.type" -> "ServicePrincipal",
  "spark.cosmos.account.subscriptionId" -> "<subscription-id>",
  "spark.cosmos.account.resourceGroupName" -> "<resource-group-name>",
  "spark.cosmos.account.tenantId" -> "<entra-tenant-id>",
  "spark.cosmos.auth.aad.clientId" -> "<entra-app-client-id>",
  "spark.cosmos.auth.aad.clientSecret" -> "<entra-app-client-secret>",
  "spark.cosmos.database" -> "<database-name>",
  "spark.cosmos.container" -> "<container-name>" 
)

Konfigurera katalog-API:et för att hantera API för NoSQL-resurser med hjälp av Spark.

# Configure Catalog Api
spark.conf.set("spark.sql.catalog.cosmosCatalog", "com.azure.cosmos.spark.CosmosCatalog")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.accountEndpoint", "<nosql-account-endpoint>")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.auth.type", "ServicePrincipal")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.account.subscriptionId", "<subscription-id>")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.account.resourceGroupName", "<resource-group-name>")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.account.tenantId", "<entra-tenant-id>")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.auth.aad.clientId", "<entra-app-client-id>")
spark.conf.set("spark.sql.catalog.cosmosCatalog.spark.cosmos.auth.aad.clientSecret", "<entra-app-client-secret>")

// Configure Catalog Api
spark.conf.set(s"spark.sql.catalog.cosmosCatalog", "com.azure.cosmos.spark.CosmosCatalog")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.accountEndpoint", "<nosql-account-endpoint>")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.auth.type", "ServicePrincipal")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.account.subscriptionId", "<subscription-id>")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.account.resourceGroupName", "<resource-group-name>")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.account.tenantId", "<entra-tenant-id>")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.auth.aad.clientId", "<entra-app-client-id>")
spark.conf.set(s"spark.sql.catalog.cosmosCatalog.spark.cosmos.auth.aad.clientSecret", "<entra-app-client-secret>")

Skapa en ny databas med hjälp CREATE DATABASE IF NOT EXISTSav . Se till att du anger databasnamnet.

# Create a database using the Catalog API
spark.sql("CREATE DATABASE IF NOT EXISTS cosmosCatalog.{};".format("<database-name>"))

// Create a database using the Catalog API
spark.sql(s"CREATE DATABASE IF NOT EXISTS cosmosCatalog.<database-name>;")

Skapa en ny container med hjälp av det databasnamn, containernamn, partitionsnyckelsökväg och dataflödesvärden som du anger.

# Create a products container using the Catalog API
spark.sql("CREATE TABLE IF NOT EXISTS cosmosCatalog.{}.{} USING cosmos.oltp TBLPROPERTIES(partitionKeyPath = '{}', manualThroughput = '{}')".format("<database-name>", "<container-name>", "<partition-key-path>", "<throughput>"))

// Create a products container using the Catalog API
spark.sql(s"CREATE TABLE IF NOT EXISTS cosmosCatalog.<database-name>.<container-name> using cosmos.oltp TBLPROPERTIES(partitionKeyPath = '<partition-key-path>', manualThroughput = '<throughput>')")

Skapa en exempeldatauppsättning.

# Create sample data    
products = (
  ("68719518391", "gear-surf-surfboards", "Yamba Surfboard", 12, 850.00, False),
  ("68719518371", "gear-surf-surfboards", "Kiama Classic Surfboard", 25, 790.00, True)
)

// Create sample data
val products = Seq(
  ("68719518391", "gear-surf-surfboards", "Yamba Surfboard", 12, 850.00, false),
  ("68719518371", "gear-surf-surfboards", "Kiama Classic Surfboard", 25, 790.00, true)
)

Använd spark.createDataFrame och oltp-konfigurationen (tidigare sparad onlinetransaktionsbearbetning) för att lägga till exempeldata i målcontainern.

# Ingest sample data    
spark.createDataFrame(products) \
  .toDF("id", "category", "name", "quantity", "price", "clearance") \
  .write \
  .format("cosmos.oltp") \
  .options(config) \
  .mode("APPEND") \
  .save()

// Ingest sample data
spark.createDataFrame(products)
  .toDF("id", "category", "name", "quantity", "price", "clearance")
  .write
  .format("cosmos.oltp")
  .options(config)
  .mode("APPEND")
  .save()

Dricks

I det här snabbstartsexemplet tilldelas autentiseringsuppgifter till variabler i klartext. För säkerhet rekommenderar vi att du använder hemligheter. Mer information om hur du konfigurerar hemligheter finns i Lägga till hemligheter i Din Spark-konfiguration.

Dela via

Använda tjänstens huvudnamn med Spark 3-anslutningsappen för Azure Cosmos DB för NoSQL

Förutsättningar

Skapa en hemlighet och registrera autentiseringsuppgifter

Skapa en definition och en tilldelning

Använda tjänstens huvudnamn

Feedback

Ytterligare resurser

Dela via

Använda tjänstens huvudnamn med Spark 3-anslutningsappen för Azure Cosmos DB för NoSQL

Förutsättningar

Skapa en hemlighet och registrera autentiseringsuppgifter

Skapa en definition och en tilldelning

Använda tjänstens huvudnamn

Relaterat innehåll

Feedback

Ytterligare resurser