Aller au contenu principal
Dernière mise à jour le

Configurer les flux Auto Loader en mode de notification de fichiers

Cette page décrit comment configurer les streams Auto Loader pour utiliser le mode de notification de fichiers afin de découvrir et d'ingérer incrémentiellement les données cloud.

En mode notification de fichiers, Auto Loader configure automatiquement un service de notification et un service de file d'attente qui s'abonnent aux événements de fichiers du répertoire d'entrée. Vous pouvez utiliser des notifications de fichiers pour monter en charge Auto Loader afin d'ingérer des millions de fichiers par heure. Comparé au mode de listage de répertoire, le mode de notification de fichiers est plus rapide et plus évolutif. De plus, vous pouvez basculer entre les notifications de fichiers et la liste de répertoires à tout moment et conserver les garanties de traitement de données « exactly-once ».

Pour une référence complète de tous les paramètres de configuration d'Auto Loader, y compris les options de notification de fichier et les options d'authentification spécifiques au cloud, consultez Auto Loader.

remarque

Bien que le mode de notification de fichier avec des événements de fichier améliore le coût et la scalabilité, il ne garantit pas l'ordre dans lequel les fichiers sont découverts ou traités. Concevez vos pipelines pour gérer les arrivées de fichiers désordonnées. Pour obtenir des conseils, consultez Gérer les données désordonnées.

Mode de notification de fichier avec et sans événements de fichier activés sur les emplacements externes​

Il existe deux façons de configurer Auto Loader pour utiliser le mode de notification de fichiers :

  • (Recommandé) Événements de fichiers: vous utilisez une seule file d'attente de notifications de fichiers pour tous les Stream qui traitent des fichiers à partir d'un emplacement externe donné. Cette approche présente les avantages suivants par rapport au mode de notification de fichiers classique :

    • Databricks peut configurer pour vous des abonnements et des événements de fichiers dans votre compte de stockage cloud sans vous demander de fournir des identifiants supplémentaires à Auto Loader à l'aide d'un identifiant de service ou d'autres options d'authentification spécifiques au cloud. Consultez Configuration des événements de fichiers pour un emplacement externe.
    • Vous avez moins de stratégies de rôle IAM à créer dans votre compte de stockage cloud.
    • Étant donné qu'il n'est plus nécessaire de créer une file d'attente pour chaque Stream Auto Loader, il est plus facile d'éviter d'atteindre les limites de notification du fournisseur de cloud répertoriées dans Ressources cloud utilisées en mode de notification de fichiers Auto Loader classique.
    • Databricks gère automatiquement l'ajustement des exigences en matière de ressources, de sorte que vous n'avez pas besoin d'ajuster des paramètres tels que cloudFiles.fetchParallelism.
    • La fonctionnalité de nettoyage signifie que vous n'avez pas autant à vous soucier du cycle de vie des notifications qui sont créées dans le cloud, par exemple lorsqu'un Stream est supprimé ou entièrement actualisé.

  • Mode de notification de fichier classique: Vous gérez les files d'attente de notification de fichiers pour chaque Stream Auto Loader séparément. Auto Loader configure automatiquement un service de notification et un service de file d'attente qui s'abonne aux événements de fichier du répertoire d'entrée. Ceci est l'approche classique.

Si vous utilisez Auto Loader en mode de listage de répertoires, Databricks recommande de migrer vers le mode de notification de fichiers avec les événements de fichier. Auto Loader avec les événements de fichier offre des améliorations de performance significatives. start by activer les événements de fichier pour votre emplacement externe, puis définissez cloudFiles.useManagedFileEvents dans votre configuration de Stream Auto Loader.

Utilisez le mode de notification de fichiers avec les événements de fichier​

Cette section décrit comment créer et mettre à jour des Auto Loader Stream pour utiliser les événements de fichiers. Databricks recommande vivement ce qui suit lors de l'utilisation du mode de notification de fichiers :

  • Utilisez les volumes Unity Catalog : Créez un volume externe distinct pour chaque chemin ou sous-répertoire à partir duquel Auto Loader charge les données. Fournissez des chemins de volume (par exemple, /Volumes/catalog/schema/volume) à Auto Loader au lieu d'URL de stockage cloud (par exemple, s3://bucket/path). Cela améliore les performances de découverte de fichiers, car le service d'événements de fichiers peut limiter la découverte de fichiers aux seuls objets pertinents, plutôt que d'itérer sur tous les objets de l'emplacement externe.
  • Utilisez un volume distinct pour chaque sous-chemin : Si vous avez plusieurs Auto Loader Stream lisant à partir de différents sous-chemins sous le même emplacement externe, créez un volume dédié pour chaque sous-chemin au lieu de partager un seul volume. Ceci évite un surcoût inutile lié à la découverte de fichiers et contribue à prévenir la limitation de débit.

Avant de commencer​

La configuration des événements de fichier nécessite :

  • Un workspace Databricks activé pour Unity Catalog.
  • Autorisation de créer des identifiants de stockage et des objets d'emplacement externe dans Unity Catalog.

Les streams Auto Loader avec événements de fichier nécessitent :

  • Compute sur Databricks Runtime 14.3 LTS ou supérieur.

Instructions de configuration​

Les instructions suivantes s'appliquent que vous créiez de nouveaux Auto Loader Stream ou que vous migriez des Stream existants pour utiliser le mode de notification de fichier mis à niveau avec des événements de fichier :

  1. Créez un identifiant de stockage et un emplacement externe dans Unity Catalog qui accordent l'accès à l'emplacement source dans le stockage cloud pour vos streams Auto Loader.
  2. Activer les événements de fichiers pour l'emplacement externe. Consultez Configuration des événements de fichiers pour un emplacement externe.
  3. Lorsque vous créez un nouveau Stream Auto Loader ou que vous en modifiez un existant pour l'utiliser avec l'emplacement externe :
    • Si vous avez des flux Auto Loader basés sur des notifications qui consomment des données à partir de l’emplacement externe, désactivez-les et supprimez les ressources de notification associées.
    • Assurez-vous que pathRewrites n'est pas défini (ce n'est pas une option courante).
    • Passez en revue la liste des paramètres qu'Auto Loader ignore lorsqu'il gère les notifications de fichiers à l'aide des événements de fichiers. Évitez-les dans les nouveaux Auto Loader Stream et supprimez-les des Stream existants que vous migrez vers ce mode.
    • Définissez l’option cloudFiles.useManagedFileEvents sur true dans votre code Auto Loader.

Par exemple :

Python
autoLoaderStream = (spark.readStream
  .format("cloudFiles")
  ...
  .options("cloudFiles.useManagedFileEvents", True)
  ...)

Si vous utilisez des LakeFlow Pipelines et que vous avez déjà un pipeline avec une table de streaming, mettez-le à jour pour inclure l'option useManagedFileEvents :

SQL
CREATE OR REFRESH STREAMING LIVE TABLE <table-name>
AS SELECT <select clause expressions>
  FROM STREAM read_files('abfss://path/to/external/location/or/volume',
                   format => '<format>',
                   useManagedFileEvents => 'True'
                   ...
                   );

Paramètres Auto Loader non pris en charge​

Les paramètres Auto Loader suivants ne sont pas pris en charge lorsque les Stream utilisent des événements de fichier :

Paramètre

Changer

useIncremental

Vous n'avez plus à choisir entre l'efficacité des notifications de fichiers et la simplicité de l'énumération des répertoires. Auto Loader avec les événements de fichiers est disponible en un seul mode.

useNotifications

Il n'y a qu'une seule file d'attente et un seul abonnement aux événements de stockage par emplacement externe.

cloudFiles.fetchParallelism

Auto Loader avec les événements de fichiers n'offre pas d'optimisation manuelle du parallélisme.

cloudFiles.backfillInterval

Databricks gère automatiquement le remplissage rétrospectif pour les emplacements externes activés pour les événements de fichiers.

cloudFiles.pathRewrites

Cette option s'applique uniquement lorsque vous montez des emplacements de données externes sur le DBFS, ce qui est obsolète.

resourceTags

Vous devez définir les tags de ressources à l'aide de la console cloud.

Paramètre

Changer

useIncremental

Vous n'avez plus à choisir entre l'efficacité des notifications de fichiers et la simplicité de l'énumération des répertoires. Auto Loader avec les événements de fichiers est disponible en un seul mode.

useNotifications

Il n'y a qu'une seule file d'attente et un seul abonnement aux événements de stockage par emplacement externe.

cloudFiles.fetchParallelism

Auto Loader avec les événements de fichiers n'offre pas d'optimisation manuelle du parallélisme.

cloudFiles.backfillInterval

Databricks gère automatiquement le remplissage rétrospectif pour les emplacements externes activés pour les événements de fichiers.

cloudFiles.pathRewrites

Cette option s'applique uniquement lorsque vous montez des emplacements de données externes sur le DBFS, ce qui est obsolète.

resourceTags

Vous devez définir les tags de ressources à l'aide de la console cloud.

Pour les meilleures pratiques relatives aux événements de fichier gérés, consultez Meilleures pratiques pour Auto Loader avec les événements de fichier.

Limitations sur Auto Loader avec des événements de fichiers​

Le service d'événements de fichier optimise la découverte de fichiers en mettant en cache les fichiers les plus récemment créés. Si Auto Loader s'exécute rarement, ce cache peut expirer, et Auto Loader recourt à la liste de répertoires pour découvrir les fichiers et mettre à jour le cache. Pour éviter ce scénario, exécutez Auto Loader au moins une fois tous les sept jours.

Pour une liste générale des limitations relatives aux événements de fichier, consultez les limitations des événements de fichier.

Gérer les files d'attente de notifications de fichiers pour chaque Stream Auto Loader séparément (classique)​

En mode de notification de fichiers classique, Auto Loader configure automatiquement un service et une file d'attente de notifications dédiés pour chaque Stream. Cette approche vous oblige à gérer les files d'attente de notifications par Stream et à fournir les identifiants d'authentification pour la création de Ressources cloud. Databricks recommande le mode de notification de fichiers pour les nouvelles workloads.

remarque

Auto Loader consomme les messages de la file d'attente de notification à mesure qu'il traite les fichiers, supprimant chaque message de la file d'attente une fois le fichier correspondant lu. C'est une opération normale et c'est la raison pour laquelle Auto Loader requiert sqs:DeleteMessage (Amazon S3), Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete (Azure) et des autorisations équivalentes de suppression de messages sur la file d'attente. Vous n'avez pas besoin de vider ou de gérer la file d'attente manuellement.

important

Vous avez besoin d'autorisations élevées pour configurer automatiquement l'infrastructure cloud pour le mode de notification de fichiers. Contactez votre administrateur cloud ou votre administrateur Workspace. Voir :

En mode de notification de fichiers classique, Auto Loader configure automatiquement un service de notification et un service de file d'attente pour chaque stream qui s'abonne aux événements de fichiers à partir du répertoire d'entrée. Vous gérez séparément les files d'attente de notifications pour chaque Auto Loader Stream.

attention

Auto Loader ne prend pas en charge la modification du chemin source en mode de notification de fichier classique. Si vous modifiez le chemin d'accès, vous risquez de ne pas ingérer les fichiers déjà présents au nouvel emplacement au moment de la mise à jour du chemin d'accès.

Ressources cloud utilisées en mode de notification de fichiers Auto Loader classique​

Auto Loader peut configurer automatiquement des notifications de fichiers pour vous lorsque vous définissez l'option cloudFiles.useNotifications sur true et que vous fournissez les autorisations nécessaires pour créer des ressources cloud. De plus, vous devrez peut-être fournir des options supplémentaires pour accorder à Auto Loader l'autorisation de créer ces ressources.

Le tableau suivant répertorie les ressources que Auto Loader crée pour chaque fournisseur de cloud.

Stockage cloud

Service d'abonnement

Service de file d'attente

Préfixe *

Limite **

Amazon S3

AWS SNS

AWS SQS

databricks-auto-ingest

100 par compartiment S3

ADLS

Azure Event Grid

Stockage File d’attente Azure

Databricks

500 par compte de stockage

GCS

Google Pub/Sub

Google Pub/Sub

databricks-auto-ingest

100 par compartiment GCS

Stockage Azure Blob

Azure Event Grid

Stockage File d’attente Azure

Databricks

500 par compte de stockage

Stockage cloud

Service d'abonnement

Service de file d'attente

Préfixe *

Limite **

Amazon S3

AWS SNS

AWS SQS

databricks-auto-ingest

100 par compartiment S3

ADLS

Azure Event Grid

Stockage File d’attente Azure

Databricks

500 par compte de stockage

GCS

Google Pub/Sub

Google Pub/Sub

databricks-auto-ingest

100 par compartiment GCS

Stockage Azure Blob

Azure Event Grid

Stockage File d’attente Azure

Databricks

500 par compte de stockage

* Auto Loader nomme les Ressources avec ce préfixe.

** Combien de pipelines de notification de fichiers simultanés peuvent être lancés ?

Si vous devez exécuter plus de Auto Loader Stream basés sur les notifications de fichiers que ce qui est autorisé par ces limites, vous pouvez utiliser les événements de fichiers ou un service tel qu'AWS Lambda, Azure Functions ou Google Cloud Functions pour distribuer les notifications d'une seule file d'attente qui écoute un conteneur ou un compartiment entier vers des files d'attente spécifiques aux répertoires.

Événements de notification de fichier classiques​

Amazon S3 fournit un événement ObjectCreated lorsqu'un fichier est upload vers un compartiment S3, qu'il ait été upload par une opération put ou un upload en plusieurs parties.

Azure Data Lake Storage fournit différentes notifications d'événements pour les fichiers qui apparaissent dans votre conteneur de stockage.

  • Auto Loader écoute l'événement FlushWithClose pour le traitement d'un fichier.
  • Les Stream Auto Loader prennent en charge l'action RenameFile pour la découverte de fichiers. Les actions RenameFile nécessitent une requête API au système de stockage pour obtenir la taille du fichier renommé.
  • Les flux Auto Loader créés avec Databricks Runtime 9.0 et versions ultérieures prennent en charge l'action RenameDirectory pour la découverte de fichiers. Les actions RenameDirectory nécessitent des requêtes API vers le système de stockage pour lister le contenu du répertoire renommé.

Google Cloud Storage fournit un événement OBJECT_FINALIZE lorsqu'un fichier est upload, ce qui inclut les remplacements et les copies de fichiers. Les upload échoués ne génèrent pas cet événement.

remarque

Les fournisseurs de cloud ne garantissent pas 100 % la livraison de tous les événements de fichiers dans de très rares cas et ne fournissent pas de SLA stricts quant à la latence des événements de fichiers. Databricks vous recommande de Trigger des remplissages réguliers avec Auto Loader en utilisant l'option cloudFiles.backfillInterval pour garantir que tous les fichiers sont découverts dans le cadre d'un SLA donné si l'exhaustivité des données est une exigence. Le déclenchement de remplissages réguliers ne provoque pas de doublons.

Autorisations requises pour la configuration des notifications de fichiers pour Azure Data Lake Storage et le Stockage Azure Blob​

Vous devez disposer d'autorisations de lecture pour le répertoire d'entrée. Voir Azure Blob Storage.

Pour utiliser le mode de notification de fichier, vous devez fournir des informations d'identification d'authentification pour la configuration et l'accès aux services de notification d'événements. Vous pouvez vous authentifier en utilisant l'une des méthodes suivantes :

Après avoir obtenu les identifiants d'authentification, veuillez attribuer les autorisations nécessaires en utilisant l'une des approches suivantes :

  • Rôles intégrés Azure :

    • Attribuez les rôles suivants au connecteur d’accès pour le compte de stockage où réside le chemin d’entrée :

      • Contributeur: Ce rôle est destiné à la configuration de ressources dans votre compte de stockage, telles que des files d'attente et des abonnements aux événements.
      • Contributeur de données de la file d’attente de stockage: Ce rôle permet d’effectuer des opérations sur les files d’attente, telles que la récupération et la suppression de messages. Ce rôle est requis uniquement si vous fournissez un Service Principal sans chaîne de connexion.

    • Attribuez au connecteur d'accès le rôle suivant au groupe de ressources associé :

      • Contributeur EventGrid EventSubscription : Ce rôle est destiné à l'exécution d'opérations d'abonnement Azure Event Grid (Event Grid) telles que la création ou la liste d'abonnements aux événements.

  • Rôle personnalisé : si vous craignez d'accorder les autorisations requises pour les rôles précédents, vous pouvez plutôt créer un rôle personnalisé avec les autorisations suivantes. Après avoir créé le rôle, attribuez-le à votre connecteur d'accès. Pour plus d'informations, consultez Attribuer des rôles Azure à l'aide du portail Azure.

    JSON
    "permissions": [
      {
        "actions": [
          "Microsoft.EventGrid/eventSubscriptions/write",
          "Microsoft.EventGrid/eventSubscriptions/read",
          "Microsoft.EventGrid/eventSubscriptions/delete",
          "Microsoft.EventGrid/locations/eventSubscriptions/read",
          "Microsoft.Storage/storageAccounts/read",
          "Microsoft.Storage/storageAccounts/write",
          "Microsoft.Storage/storageAccounts/queueServices/read",
          "Microsoft.Storage/storageAccounts/queueServices/write",
          "Microsoft.Storage/storageAccounts/queueServices/queues/write",
          "Microsoft.Storage/storageAccounts/queueServices/queues/read",
          "Microsoft.Storage/storageAccounts/queueServices/queues/delete"
      ],
        "notActions": [],
        "dataActions": [
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete",
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/read",
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/write",
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action"
        ],
        "notDataActions": []
      }
    ]

    Paramètres d&#39;autorisation d&#39;Auto Loader

Autorisations requises pour la configuration des notifications de fichiers pour Amazon S3​

Vous devez disposer d'autorisations de lecture pour le répertoire d'entrée. Consultez les détails de la connexion S3 pour plus d'informations.

Pour utiliser le mode de notification de fichiers, joignez le document de stratégie JSON suivant à votre utilisateur ou rôle IAM. Ce rôle IAM est requis pour créer un identifiant de service Databricks permettant à Auto Loader de s'authentifier. La prise en charge des identifiants de service est disponible dans Databricks Runtime 16,1 et versions ultérieures.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DatabricksAutoLoaderSetup",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "s3:PutBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes",
        "sns:CreateTopic",
        "sns:TagResource",
        "sns:Publish",
        "sns:Subscribe",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:SetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:sqs:<region>:<account-number>:databricks-auto-ingest-*",
        "arn:aws:sns:<region>:<account-number>:databricks-auto-ingest-*"
      ]
    },
    {
      "Sid": "DatabricksAutoLoaderList",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": "*"
    },
    {
      "Sid": "DatabricksAutoLoaderTeardown",
      "Effect": "Allow",
      "Action": ["sns:Unsubscribe", "sns:DeleteTopic", "sqs:DeleteQueue"],
      "Resource": [
        "arn:aws:sqs:<region>:<account-number>:databricks-auto-ingest-*",
        "arn:aws:sns:<region>:<account-number>:databricks-auto-ingest-*"
      ]
    }
  ]
}

Remplacez les espaces réservés suivants par les valeurs de votre environnement :

  • <bucket-name>: le nom du compartiment S3 où votre Stream lira les fichiers, par exemple, auto-logs. Vous pouvez utiliser * comme caractère générique, par exemple, databricks-*-logs. Pour découvrir le compartiment S3 sous-jacent à votre chemin DBFS, vous pouvez répertorier tous les points de montage DBFS dans un Notebook en exécutant %fs mounts.
  • <region>: La région AWS où réside le compartiment S3, par exemple, us-west-2. Si vous ne souhaitez pas spécifier la région, utilisez *.
  • <account-number>: Le numéro de compte AWS qui détient le compartiment S3, par exemple, 123456789012. Si vous ne souhaitez pas spécifier le numéro de compte, utilisez *.

La chaîne databricks-auto-ingest-* dans la spécification d'ARN SQS et SNS est le préfixe de nom que la source cloudFiles utilise lors de la création des services SQS et SNS. Étant donné que Databricks configure les services de notification lors de la première exécution du stream, vous pouvez utiliser une politique avec des autorisations réduites après la première exécution (par exemple, pour arrêter le stream, puis le redémarrer).

remarque

La politique précédente ne concerne que les autorisations nécessaires à la configuration des services de notification de fichiers, à savoir les services de notification de compartiment S3, SNS et SQS, et suppose que vous disposez déjà d'un accès en lecture au compartiment S3. Si vous devez ajouter des autorisations de lecture seule S3, ajoutez ce qui suit à la liste Action dans l'instruction DatabricksAutoLoaderSetup du document JSON :

  • s3:ListBucket
  • s3:GetObject

Autorisations réduites après la configuration initiale​

Vous n'avez besoin que des autorisations de configuration des Ressources décrites ci-dessus lors de l'exécution initiale du Stream. Après la première exécution, vous pouvez passer à la stratégie IAM suivante avec des autorisations réduites. Cependant, avec des autorisations réduites, vous ne pouvez pas start de nouvelles requêtes de streaming, recréer des Ressources après des échecs tels qu'une file d'attente SQS supprimée accidentellement, ou utiliser l'API de gestion des ressources cloud pour lister ou supprimer des Ressources.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DatabricksAutoLoaderUse",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:TagResource",
        "sns:Publish",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "arn:aws:sqs:<region>:<account-number>:<queue-name>",
        "arn:aws:sns:<region>:<account-number>:<topic-name>",
        "arn:aws:s3:::<bucket-name>"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
      "Resource": ["arn:aws:s3:::<bucket-name>"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:PutObjectAcl", "s3:GetObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::<bucket-name>/*"]
    },
    {
      "Sid": "DatabricksAutoLoaderListTopics",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": "arn:aws:sns:<region>:<account-number>:*"
    }
  ]
}

Ingérez les données en toute sécurité dans un autre compte AWS​

Auto Loader peut charger des données entre les comptes AWS en assumant un rôle IAM à l'aide de AssumeRole. Pour configurer Auto Loader pour l'ingestion inter-comptes, suivez les étapes décrites dans Accéder aux compartiments S3 inter-comptes avec une politique AssumeRole. Vérifiez ensuite que vous disposez du rôle méta AssumeRole attribué au cluster et configurez la configuration Spark du cluster pour inclure les propriétés suivantes :

ini
fs.s3a.credentialsType AssumeRole
fs.s3a.stsAssumeRole.arn arn:aws:iam::<bucket-owner-acct-id>:role/MyRoleB
fs.s3a.acl.default BucketOwnerFullControl

Autorisations requises pour la configuration des notifications de fichiers pour GCS​

Pour utiliser le mode de notification de fichiers, vous devez configurer les autorisations :

  • Assurez-vous de disposer des autorisations list et get sur votre bucket GCS et sur tous les objets. Pour plus de détails, consultez la documentation Google sur les autorisations IAM.

  • Ajoutez le rôle Pub/Sub Publisher au compte de service GCS. Cela permet au compte de publier des messages de notification d'événements depuis vos buckets GCS vers Google Cloud Pub/Sub.

  • Ajoutez les autorisations suivantes au compte de service utilisé pour les ressources Google Cloud Pub/Sub. Vous pouvez soit créer un rôle IAM personnalisé avec ces autorisations, soit leur attribuer des rôles GCP préexistants. Databricks crée automatiquement ce compte de service lorsque vous créez un identifiant de service. La prise en charge des identifiants de service est disponible dans Databricks Runtime 16.1 et versions ultérieures.

    pubsub.subscriptions.consume
    pubsub.subscriptions.create
    pubsub.subscriptions.delete
    pubsub.subscriptions.get
    pubsub.subscriptions.list
    pubsub.subscriptions.update
    pubsub.topics.attachSubscription
    pubsub.topics.detachSubscription
    pubsub.topics.create
    pubsub.topics.delete
    pubsub.topics.get
    pubsub.topics.list
    pubsub.topics.update

Recherche du compte de service GCS​

Accédez à *Stockage cloud > Paramètres* dans la console Google Cloud pour le projet correspondant. La section *Compte de service de stockage cloud* contient l'e-mail du compte de service GCS.

Compte de service GCS

Création d'un rôle IAM personnalisé Google Cloud pour le Mode de notification de fichiers​

Accédez à IAM & Admin > Rôles dans la console Google Cloud pour le projet correspondant. Ensuite, créez un rôle ou mettez à jour un rôle existant. Sur la page *Créer un rôle*, sélectionnez *Ajouter des autorisations*. Dans le menu, ajoutez les autorisations souhaitées au rôle.

Rôles IAM personnalisés GCP

Configurer ou gérer manuellement les ressources de notification de fichiers​

Les utilisateurs privilégiés peuvent configurer ou gérer manuellement les ressources de notification de fichiers. Pour configurer les services de notification de fichiers via le fournisseur de cloud et spécifier l’identifiant de la file d’attente, consultez Notification de fichier. Pour utiliser les APIs Scala afin de créer ou de gérer les services de notification et de mise en file d'attente à la place :

remarque

Vous devez disposer des autorisations appropriées pour configurer ou modifier l'infrastructure cloud. Consultez la documentation des autorisations pour Azure, S3, ou GCS.

Étape 1 : Créez un ResourceManager dans AWS, Azure ou Google Cloud​

Python

# Create a ResourceManager in AWS

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesAWSResourceManager \
  .newManager() \
  .option("cloudFiles.region", <region>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .create()

# Using an AWS access key and secret key
manager = spark._jvm.com.databricks.sql.CloudFilesAWSResourceManager \
  .newManager() \
  .option("cloudFiles.region", <region>) \
  .option("cloudFiles.awsAccessKey", <aws-access-key>) \
  .option("cloudFiles.awsSecretKey", <aws-secret-key>) \
  .option("cloudFiles.roleArn", <role-arn>) \
  .option("cloudFiles.roleExternalId", <role-external-id>) \
  .option("cloudFiles.roleSessionName", <role-session-name>) \
  .option("cloudFiles.stsEndpoint", <sts-endpoint>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

Python

# Create a ResourceManager in Azure

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesAzureResourceManager \
  .newManager() \
  .option("cloudFiles.resourceGroup", <resource-group>) \
  .option("cloudFiles.subscriptionId", <subscription-id>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .option("path", <path-to-specific-container-and-folder>) \
  .create()

# Using an Azure service principal
manager = spark._jvm.com.databricks.sql.CloudFilesAzureResourceManager \
  .newManager() \
  .option("cloudFiles.connectionString", <connection-string>) \
  .option("cloudFiles.resourceGroup", <resource-group>) \
  .option("cloudFiles.subscriptionId", <subscription-id>) \
  .option("cloudFiles.tenantId", <tenant-id>) \
  .option("cloudFiles.clientId", <service-principal-client-id>) \
  .option("cloudFiles.clientSecret", <service-principal-client-secret>) \
  .option("path", <path-to-specific-container-and-folder>) \
  .create()

Python

# Create a ResourceManager in GCP

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesGCPResourceManager \
  .newManager() \
  .option("cloudFiles.projectId", <project-id>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

# Using a Google service account
manager = spark._jvm.com.databricks.sql.CloudFilesGCPResourceManager \
  .newManager() \
  .option("cloudFiles.projectId", <project-id>) \
  .option("cloudFiles.client", <client-id>) \
  .option("cloudFiles.clientEmail", <client-email>) \
  .option("cloudFiles.privateKey", <private-key>) \
  .option("cloudFiles.privateKeyId", <private-key-id>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

Étape 2 : Utilisez le gestionnaire de ressources pour configurer, visualiser et démanteler les services de notification de fichiers.​

Python

# Set up a queue and a topic subscribed to the path provided in the manager.
manager.setUpNotificationServices(<resource-suffix>)

# List notification services created by <AL>.
from pyspark.sql import DataFrame
df = DataFrame(manager.listNotificationServices(), spark)

# Tear down the notification services created for a specific stream ID.
# Stream ID is a GUID string that you can find in the list result above.
manager.tearDownNotificationServices(<stream-id>)

Utilisez setUpNotificationServices(<resource-suffix>) pour créer une file d'attente et un abonnement avec le nom <prefix>-<resource-suffix> (le préfixe dépend du système de stockage résumé dans Ressources cloud utilisées en mode de notification de fichiers Auto Loader classique). S'il existe une ressource avec le même nom, Databricks réutilise la ressource existante au lieu d'en créer une nouvelle. Cette fonction renvoie un identifiant de file d'attente que vous pouvez transmettre à la source cloudFiles en utilisant l'identifiant dans Notification de fichier. Cela permet à l'utilisateur source cloudFiles d'avoir moins d'autorisations que l'utilisateur qui crée les ressources.

Fournissez l'option "path" à newManager uniquement si vous appelez setUpNotificationServices. Ce n'est pas nécessaire pour listNotificationServices ou tearDownNotificationServices. C'est le même path que vous utilisez lors de l'exécution d'une query de streaming.

La matrice suivante indique quelles méthodes API sont prises en charge dans quel Databricks Runtime pour chaque type de stockage :

Stockage cloud

Configuration de l'API

API de liste

Désactiver l'API

Amazon S3

Toutes les versions

Toutes les versions

Toutes les versions

ADLS

Toutes les versions

Toutes les versions

Toutes les versions

GCS

Databricks Runtime 9.1 et versions ultérieures

Databricks Runtime 9.1 et versions ultérieures

Databricks Runtime 9.1 et versions ultérieures

Stockage Azure Blob

Toutes les versions

Toutes les versions

Toutes les versions

Stockage cloud

Configuration de l'API

API de liste

Désactiver l'API

Amazon S3

Toutes les versions

Toutes les versions

Toutes les versions

ADLS

Toutes les versions

Toutes les versions

Toutes les versions

GCS

Databricks Runtime 9.1 et versions ultérieures

Databricks Runtime 9.1 et versions ultérieures

Databricks Runtime 9.1 et versions ultérieures

Stockage Azure Blob

Toutes les versions

Toutes les versions

Toutes les versions

Nettoyer les ressources de notification d'événements créées par Auto Loader​

Auto Loader ne supprime pas automatiquement les ressources de notification de fichiers. Pour supprimer les ressources de notification de fichiers, vous devez utiliser le gestionnaire de ressources cloud, comme indiqué dans la section précédente. Vous pouvez également supprimer ces ressources manuellement à l'aide de l'interface utilisateur ou des APIs du fournisseur cloud.

Dépanner les erreurs courantes​

Cette section décrit les erreurs courantes lors de l'utilisation d'Auto Loader en mode de notification de fichier et comment les résoudre.

Échec de la création de l'abonnement Event Grid​

Si vous voyez le message d'erreur suivant lorsque vous exécutez Auto Loader pour la première fois, vous n'avez pas enregistré Event Grid en tant que fournisseur de ressources dans l'abonnement Azure.

java.lang.RuntimeException: Failed to create event grid subscription.

Pour enregistrer Event Grid en tant que fournisseur de ressources, procédez comme suit :

  1. Dans le portail Azure, accédez à votre abonnement.
  2. Sélectionnez Fournisseurs de ressources dans la section Paramètres.
  3. Enregistrez le prestataire Microsoft.EventGrid.

Autorisation requise pour effectuer des opérations d'abonnement Event Grid​

Si vous voyez le message d'erreur suivant lorsque vous exécutez Auto Loader pour la première fois, confirmez que le rôle de Contributeur est attribué au service principal pour Event Grid et le compte de stockage.

403 Forbidden ... does not have authorization to perform action 'Microsoft.EventGrid/eventSubscriptions/[read|write]' over scope ...

Le client Event Grid contourne le proxy​

Dans Databricks Runtime 15.2 ou supérieur, les connexions Event Grid dans Auto Loader utilisent les paramètres de proxy des propriétés système par default. Dans Databricks Runtime 13.3 LTS, 14.3 LTS et 15.0 à 15.2, vous pouvez configurer manuellement les connexions Event Grid pour utiliser un proxy en définissant la propriété **Spark Config**. spark.databricks.cloudFiles.eventGridClient.useSystemProperties true Consultez Définir les propriétés de configuration Spark sur Databricks.

Trop de requêtes​

Si vous voyez le message d'erreur suivant dans les logs de votre Stream Auto Loader, cela indique que vos Streams dépassent la limite de débit pour le service d'événements de fichiers Databricks :

com.databricks.sql.util.UnexpectedHttpStatus: Too many requests. Please wait a moment and try again.

Cela se produit généralement lorsque plusieurs flux Auto Loader lisent à partir de différents sous-chemins sous le même emplacement externe sans utiliser de volumes Unity Catalog. Le service d'événements de fichiers doit itérer sur tous les objets de l'emplacement externe pour trouver les fichiers pertinents pour chaque stream, ce qui entraîne des appels API excessifs. Pour résoudre ce problème, suivez les recommandations décrites dans Utiliser le mode de notification de fichiers avec les événements de fichiers.

Ressources supplémentaires​

Sur cette page