Een service-principal gebruiken met de Spark 3-connector voor Azure Cosmos DB voor NoSQL

Artikel
08/15/2024

In dit artikel leert u hoe u een Microsoft Entra-toepassing en service-principal maakt die kan worden gebruikt met op rollen gebaseerd toegangsbeheer. U kunt deze service-principal vervolgens gebruiken om verbinding te maken met een Azure Cosmos DB for NoSQL-account vanuit Spark 3.

Vereisten

Een bestaand Azure Cosmos DB for NoSQL-account.
- Als u een bestaand Azure-abonnement hebt, maakt u een nieuw account.
- Geen Azure-abonnement? U kunt Azure Cosmos DB gratis proberen zonder dat er een creditcard is vereist.
Een bestaande Azure Databricks-werkruimte.
Geregistreerde Microsoft Entra-toepassing en service-principal.
- Als u geen service-principal en toepassing hebt, registreert u een toepassing met behulp van Azure Portal.

Een geheim maken en referenties vastleggen

In deze sectie maakt u een clientgeheim en registreert u de waarde voor later gebruik.

Open de Azure Portal.
Ga naar uw bestaande Microsoft Entra-toepassing.
Ga naar de pagina Certificaten en geheimen . Maak vervolgens een nieuw geheim. Sla de waarde voor het clientgeheim op die verderop in dit artikel moet worden gebruikt.
Ga naar de pagina Overzicht. Zoek en noteer de waarden voor de id van de toepassing (client), object-id en map-id (tenant). U gebruikt deze waarden ook verderop in dit artikel.
Ga naar uw bestaande Azure Cosmos DB for NoSQL-account.
Noteer de URI-waarde op de pagina Overzicht . Noteer ook de waarden voor de abonnements-id en de resourcegroep. U gebruikt deze waarden verderop in dit artikel.

Een definitie en een toewijzing maken

In deze sectie maakt u een Microsoft Entra ID-roldefinitie. Vervolgens wijst u die rol toe met machtigingen voor het lezen en schrijven van items in de containers.

Maak een rol met behulp van de az role definition create opdracht. Geef de azure Cosmos DB for NoSQL-accountnaam en resourcegroep door, gevolgd door een hoofdtekst van JSON die de aangepaste rol definieert. De rol is ook afgestemd op het accountniveau met behulp van /. Zorg ervoor dat u een unieke naam opgeeft voor uw rol met behulp van de RoleName eigenschap van de aanvraagbody.

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/*"
            ]
        }]
    }'

Vermeld de roldefinitie die u hebt gemaakt om de unieke id op te halen in de JSON-uitvoer. Noteer de id waarde van de JSON-uitvoer.

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": []
      }
    ],
    ...
  }
]

Hiermee az cosmosdb sql role assignment create maakt u een roltoewijzing. Vervang door <aad-principal-id> de object-id die u eerder in dit artikel hebt vastgelegd. <role-definition-id> Vervang ook door de id waarde die is opgehaald uit het uitvoeren van de az cosmosdb sql role definition list opdracht in een vorige stap.
```
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>"
```

Een service-principal gebruiken

Nu u een Microsoft Entra-toepassing en service-principal hebt gemaakt, een aangepaste rol hebt gemaakt en die rolmachtigingen hebt toegewezen aan uw Azure Cosmos DB for NoSQL-account, moet u een notebook kunnen uitvoeren.

Open uw Azure Databricks-werkruimte.
Maak een nieuw cluster in de werkruimte-interface. Configureer het cluster met deze instellingen minimaal:

Versie Weergegeven als

Runtime-versie 13.3 LTS (Scala 2.12, Spark 3.4.1)
Gebruik de werkruimte-interface om te zoeken naar Maven-pakketten van Maven Central met een groeps-id van com.azure.cosmos.spark. Installeer het pakket specifiek voor Spark 3.4 met een artefact-id die is voorafgegaan door azure-cosmos-spark_3-4 het cluster.
Maak ten slotte een nieuw notitieblok.

Tip

Standaard wordt het notebook gekoppeld aan het onlangs gemaakte cluster.

Versie	Weergegeven als
Runtime-versie	`13.3 LTS (Scala 2.12, Spark 3.4.1)`

Stel in het notebook de configuratie-instellingen voor de Azure Cosmos DB Spark-connector in voor het NoSQL-accounteindpunt, de databasenaam en de containernaam. Gebruik de waarden abonnements-id, resourcegroep, toepassings-id (client), map-id (tenant) en waarden voor clientgeheimen die eerder in dit artikel zijn vastgelegd.

# 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>" 
)

Configureer de Catalogus-API voor het beheren van API voor NoSQL-resources met behulp van 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>")

Maak een nieuwe database met behulp van CREATE DATABASE IF NOT EXISTS. Zorg ervoor dat u de databasenaam opgeeft.

# 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>;")

Maak een nieuwe container met behulp van de databasenaam, containernaam, partitiesleutelpad en doorvoerwaarden die u opgeeft.

# 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>')")

Maak een voorbeeldgegevensset.

# 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)
)

Gebruik spark.createDataFrame en de eerder opgeslagen OLTP-configuratie (Online Transaction Processing) om voorbeeldgegevens toe te voegen aan de doelcontainer.

# 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()

Tip

In dit snelstartvoorbeeld worden referenties toegewezen aan variabelen in duidelijke tekst. Voor beveiliging raden we u aan geheimen te gebruiken. Zie Geheimen toevoegen aan uw Spark-configuratie voor meer informatie over het configureren van geheimen.

Delen via

Een service-principal gebruiken met de Spark 3-connector voor Azure Cosmos DB voor NoSQL

Vereisten

Een geheim maken en referenties vastleggen

Een definitie en een toewijzing maken

Een service-principal gebruiken

Feedback

Aanvullende resources

Delen via

Een service-principal gebruiken met de Spark 3-connector voor Azure Cosmos DB voor NoSQL

Vereisten

Een geheim maken en referenties vastleggen

Een definitie en een toewijzing maken

Een service-principal gebruiken

Gerelateerde inhoud

Feedback

Aanvullende resources