Inserire dati da SharePoint

:::nota Conformità

Il connettore di SharePoint gestito supporta l'uso nelle aree di lavoro con le impostazioni di configurazione della sicurezza e della conformità avanzate abilitate.

:::

Questa pagina illustra come creare una pipeline di inserimento di Microsoft SharePoint gestita tramite Lakeflow Connect.

Prima di iniziare

  • Per creare la pipeline di inserimento, è prima necessario soddisfare i requisiti seguenti:

    • L'area di lavoro deve essere abilitata per Unity Catalog.

    • L'ambiente di calcolo serverless deve essere abilitato per l'area di lavoro. Consulta Requisiti di calcolo serverless.

    • Per creare una nuova connessione, è necessario disporre dei privilegi CREATE CONNECTION sul metastore. Consulta Gestione dei privilegi in Unity Catalog.

      Se il connettore supporta la creazione di pipeline basate sull'interfaccia utente, un amministratore può creare la connessione e la pipeline contemporaneamente completando i passaggi in questa pagina. Tuttavia, se gli utenti che creano pipeline utilizzano pipeline create tramite API o sono utenti non amministratori, un amministratore deve prima creare la connessione in Esplora Cataloghi. Vedere Connettersi alle origini di inserimento gestite.

    • Per usare una connessione esistente, è necessario disporre dei privilegi USE CONNECTION o di ALL PRIVILEGES sull'oggetto connessione.

    • È necessario disporre dei privilegi USE CATALOG sul catalogo di destinazione.

    • È necessario disporre di privilegi USE SCHEMA e CREATE TABLE su uno schema esistente o di privilegi CREATE SCHEMA sul catalogo di destinazione.

  • Per inserire da SharePoint, è prima necessario configurare un metodo di autenticazione supportato. Consulta Configurare OAuth U2M: gestito da Databricks (consigliato).

Creare un flusso di inserimento dati

Per un elenco dei formati di file supportati e delle limitazioni specifiche del connettore, vedere Microsoft SharePoint limitazioni del connettore.

Interfaccia utente di Databricks

  1. Nella barra laterale dell'area di lavoro di Azure Databricks fare clic su Inserimento dati.
  2. Nella sezione Connettori Databricks della pagina Aggiungi dati fare clic su Microsoft SharePoint.
  3. Nel passaggio Connessione della procedura guidata di inserimento selezionare la connessione in cui sono archiviate le credenziali di accesso SharePoint. Se si dispone del privilegio CREATE CONNECTION nel metastore, è possibile fare clic su l'icona più. Crea connessione per creare una nuova connessione con i dettagli di autenticazione in Panoramica della configurazione dell'acquisizione di SharePoint.
  4. Fare clic su Avanti.
  5. Nel passaggio configurazione dell'acquisizione, immetti un nome per la pipeline.
  6. Selezionare un catalogo e uno schema per la pipeline. Se si dispone di USE CATALOG e CREATE SCHEMA privilegi sul catalogo, è possibile fare clic sull'icona Plus. Creare uno schema nel menu a discesa per creare un nuovo schema.
  7. Fare clic su Crea pipeline di inserimento e avviare il calcolo.
  8. Nel passaggio Origine, configura l'URL di SharePoint e le opzioni di acquisizione dei file.
  9. Fare clic su Salva e continua.
  10. Nel passaggio Destinazione selezionare un catalogo e uno schema in cui caricare i dati. Se si dispone di USE CATALOG e CREATE SCHEMA privilegi sul catalogo, è possibile fare clic sull'icona Plus. Creare uno schema nel menu a discesa per creare un nuovo schema.
  11. Fare clic su Salva e continua.
  12. (Facoltativo) Nel passaggio Pianificazioni e notifiche fare clic sull'icona Più. Creare una pianificazione. Impostare la frequenza per aggiornare le tabelle di destinazione.
  13. (Facoltativo) Fare clic sull'icona Con il segno più. Aggiungere una notifica per impostare le notifiche di posta elettronica per l'esito positivo o negativo dell'operazione della pipeline, quindi fare clic su Salva ed esegui pipeline.

Notebook di Databricks

  1. Importare il notebook seguente nell'area di lavoro di Azure Databricks:

    Ottieni il notebook

  2. Non modificare la cella 1.

  3. Modificare la cella 3 con i dettagli della configurazione della pipeline. Vedere pipeline.ingestion_definition ed esempi.

  4. Fare clic su Esegui tutto.

Pacchetti di automazione dichiarativa

Usare bundle di automazione dichiarativa per gestire SharePoint pipeline come codice. I bundle possono contenere definizioni YAML di processi e attività, vengono gestiti tramite l'interfaccia della riga di comando di Databricks e possono essere condivisi ed eseguiti in aree di lavoro di destinazione diverse, ad esempio sviluppo, gestione temporanea e produzione. Per altre informazioni, vedere Che cosa sono i bundle di automazione dichiarativa?.

  1. Creare un bundle usando l'interfaccia della riga di comando di Databricks:

    databricks bundle init

  2. Aggiungere due nuovi file di risorse al bundle:

    • Un file di definizione della pipeline , ad esempio resources/sharepoint_pipeline.yml. Vedere pipeline.ingestion_definition ed esempi.
    • File di definizione del processo che controlla la frequenza di inserimento dei dati , ad esempio resources/sharepoint_job.yml.

  3. Distribuire la pipeline usando la CLI di Databricks.

    databricks bundle deploy

Examples

Usare questi esempi per configurare la pipeline.

Ingestimento dei file come dati non strutturati

Inserire tutti i file in un sito SharePoint come contenuto binario. Usare questo approccio per file PDF, documenti di Office e altri file che si intende elaborare downstream, ad esempio per le applicazioni RAG.

Nota

Disponibile in Beta, il FILE tipo memorizza un riferimento regolato a ciascun file e ai suoi metadati invece dei byte del file, migliorando così le prestazioni di lettura. Per ingerire file come FILE tipo invece di BINARYFILE, vedi i file Ingest come tipo FILE (Beta).

Pacchetti di automazione dichiarativa

resources:
  pipelines:
    sharepoint_binary_pipeline:
      name: sharepoint_binary_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <sharepoint-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: site_files
              connector_options:
                sharepoint_options:
                  entity_type: FILE
                  url: https://<tenant>.sharepoint.com/sites/<site>
                  file_ingestion_options:
                    format: BINARYFILE
                    schema_evolution_mode: NONE

Notebook di Databricks

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "ingestion_definition": {
    "connection_name": "<sharepoint-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "destination_table": "site_files",
          "connector_options": {
            "sharepoint_options": {
              "entity_type": "FILE",
              "url": "https://<tenant>.sharepoint.com/sites/<site>",
              "file_ingestion_options": {
                "format": "BINARYFILE",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}
"""
create_pipeline(pipeline_spec)

Ingesta file come tipo FILE (Beta)

Importante

Questa funzionalità è in versione beta. Gli amministratori dell'area di lavoro possono controllare l'accesso a questa funzionalità dalla pagina Anteprime . Vedere Gestire le anteprime di Azure Databricks.

Ingest file come FILE il tipo per memorizzare un riferimento governato a ogni file e ai suoi metadati invece dei byte del file. La tabella di destinazione espone una file colonna che puoi passare a funzioni come ai_parse_document funzione e a funzioni definite dall'utente (UDF).

Per utilizzare il FILE tipo, configura quanto segue nella tua pipeline:

  • Imposta la pipeline channel su PREVIEW.
  • Impostare file_ingestion_options.format su FILE.
  • Imposta la databricks.filespace-preview proprietà tabella per dichiarare il volume che Unity Catalog utilizza come storage gestito.

Pacchetti di automazione dichiarativa

resources:
  pipelines:
    sharepoint_file_pipeline:
      name: sharepoint_file_pipeline
      channel: PREVIEW
      catalog: <catalog>
      schema: <schema>
      ingestion_definition:
        connection_name: <sharepoint-connection>
        objects:
          - table:
              destination_catalog: <catalog>
              destination_schema: <schema>
              destination_table: <destination-table>
              table_configuration:
                table_properties:
                  databricks.filespace-preview: /Volumes/<catalog>/<schema>/<volume>/
              connector_options:
                sharepoint_options:
                  entity_type: FILE
                  url: https://<tenant>.sharepoint.com/sites/<site>
                  file_ingestion_options:
                    format: FILE
                    schema_evolution_mode: NONE

Notebook di Databricks

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "channel": "PREVIEW",
  "catalog": "<catalog>",
  "schema": "<schema>",
  "ingestion_definition": {
    "connection_name": "<sharepoint-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "<catalog>",
          "destination_schema": "<schema>",
          "destination_table": "<destination-table>",
          "table_configuration": {
            "table_properties": {
              "databricks.filespace-preview": "/Volumes/<catalog>/<schema>/<volume>/"
            }
          },
          "connector_options": {
            "sharepoint_options": {
              "entity_type": "FILE",
              "url": "https://<tenant>.sharepoint.com/sites/<site>",
              "file_ingestion_options": {
                "format": "FILE",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  }
}
"""
create_pipeline(pipeline_spec)

Inserire file strutturati

Inserire file strutturati ,ad esempio file JSON, da una cartella SharePoint. Ogni riga nei file di origine diventa una riga nella tabella di destinazione.

Pacchetti di automazione dichiarativa

resources:
  pipelines:
    sharepoint_json_pipeline:
      name: sharepoint_json_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <sharepoint-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: json_files
              connector_options:
                sharepoint_options:
                  entity_type: FILE
                  url: https://<tenant>.sharepoint.com/sites/<site>/<json_folder>
                  file_ingestion_options:
                    format: JSON
                    schema_evolution_mode: NONE

Notebook di Databricks

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "ingestion_definition": {
    "connection_name": "<sharepoint-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "destination_table": "json_files",
          "connector_options": {
            "sharepoint_options": {
              "entity_type": "FILE",
              "url": "https://<tenant>.sharepoint.com/sites/<site>/<json_folder>",
              "file_ingestion_options": {
                "format": "JSON",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}
"""
create_pipeline(pipeline_spec)

Acquisisci solo i metadati del file

Inserire i metadati del file (nome, dimensioni, timestamp, percorso) senza scaricare il contenuto del file. Usare questo approccio quando è necessario un inventario dei file senza il sovraccarico di inserimento del contenuto.

Pacchetti di automazione dichiarativa

resources:
  pipelines:
    sharepoint_metadata_pipeline:
      name: sharepoint_metadata_pipeline
      catalog: main
      schema: ingest_destination_schema
      channel: PREVIEW
      ingestion_definition:
        connection_name: <sharepoint-connection>
        objects:
          - table:
              destination_catalog: main
              destination_schema: ingest_destination_schema
              destination_table: file_metadata
              connector_options:
                sharepoint_options:
                  entity_type: FILE_METADATA
                  url: https://<tenant>.sharepoint.com/sites/<site>/<library>
                  file_ingestion_options:
                    format: BINARYFILE
                    schema_evolution_mode: NONE

Notebook di Databricks

pipeline_spec = """
{
  "name": "<pipeline-name>",
  "catalog": "main",
  "schema": "ingest_destination_schema",
  "ingestion_definition": {
    "connection_name": "<sharepoint-connection>",
    "objects": [
      {
        "table": {
          "destination_catalog": "main",
          "destination_schema": "ingest_destination_schema",
          "destination_table": "file_metadata",
          "connector_options": {
            "sharepoint_options": {
              "entity_type": "FILE_METADATA",
              "url": "https://<tenant>.sharepoint.com/sites/<site>/<library>",
              "file_ingestion_options": {
                "format": "BINARYFILE",
                "schema_evolution_mode": "NONE"
              }
            }
          }
        }
      }
    ]
  },
  "channel": "PREVIEW"
}
"""
create_pipeline(pipeline_spec)

File di definizione delle attività per i bundle di automazione dichiarativa

Di seguito è riportato un file di definizione del job di esempio da usare con Bundle di Automazione Dichiarativa. L'attività viene eseguita ogni giorno, esattamente un giorno dopo l'ultima esecuzione.

Pacchetti di automazione dichiarativa

resources:
  jobs:
    sharepoint_job:
      name: sharepoint_job

      trigger:
        periodic:
          interval: 1
          unit: DAYS

      email_notifications:
        on_failure:
          - <email-address>

      tasks:
        - task_key: refresh_pipeline
          pipeline_task:
            pipeline_id: ${resources.pipelines.sharepoint_binary_pipeline.id}

Configurare le opzioni di inserimento file

Il file_ingestion_options blocco controlla la modalità di elaborazione dei file. Tutte le opzioni vengono impostate all'interno del sharepoint_options.file_ingestion_options blocco nella definizione della pipeline.

Filtri file

Usare file_filters per limitare i file inseriti dall'URL di origine:

"file_ingestion_options": {
  "format": "CSV",
  "file_filters": [
    { "path_filter": "invoices/*.csv" },
    { "modified_after": "2026-01-01T00:00:00" }
  ]
}

Per il file_ingestion_optionsriferimento completo ai parametri, vedere riferimento del connettore Microsoft SharePoint.

Evoluzione dello schema

Impostare schema_evolution_mode per controllare la modalità di gestione delle nuove colonne nei file in ingresso. Le modalità corrispondono alle modalità di evoluzione dello schema del caricatore automatico. Per informazioni dettagliate, vedere informazioni di riferimento sul connettore Microsoft SharePoint.

Suggerimenti per lo schema

Sovrascrivere i tipi di colonna rilevati usando schema_hints:

"file_ingestion_options": {
  "format": "CSV",
  "schema_hints": "order_id INT, amount DOUBLE, ts TIMESTAMP"
}

Per i dettagli sull'utilizzo, vedere Sostituire l'inferenza dello schema con suggerimenti sullo schema.

Opzioni specifiche del formato

Passare opzioni specifiche del formato usando format_options:

"file_ingestion_options": {
  "format": "CSV",
  "format_options": {
    "header": "true",
    "sep": ","
  }
}

Le chiavi supportate sono le opzioni di formato standard del caricatore automatico. Vedere Opzioni di formato.

Modelli comuni

Per le configurazioni avanzate della pipeline, vedere Modelli comuni per le pipeline di inserimento gestite.

Passaggi successivi

  • Avvia, pianifica e imposta avvisi sulla tua pipeline. Vedere Attività comuni di manutenzione della pipeline.
  • È possibile analizzare i documenti non elaborati in testo, suddividere i dati analizzati, creare incorporamenti dai blocchi e altro ancora. È quindi possibile usare readStream nella tabella di output direttamente nella pipeline downstream. Vedere Caso d'uso di RAG downstream.

Risorse aggiuntive

  • Last updated on