Ingesta de archivos de SharePoint

:::note Cumplimiento

El conector SharePoint admite el uso en áreas de trabajo con la Configuración mejorada de la configuración de seguridad y cumplimiento habilitada.

:::

Puede ingerir archivos estructurados, semiestructurados y no estructurados de Microsoft SharePoint en tablas Delta. El conector de SharePoint admite la ingesta incremental de archivos de SharePoint mediante API de streaming y por lotes, incluido Auto Loader, spark.read y COPY INTO, todo ello con la gobernanza del Unity Catalog.

Choose el conector de SharePoint

Lakeflow Connect ofrece dos conectores complementarios SharePoint. Ambos acceden a los datos en SharePoint, pero admiten objetivos distintos.

Características clave

El conector SharePoint estándar ofrece:

• Ingesta de archivos estructurados, semiestructurados y no estructurados
• Ingesta granular: ingiere un sitio específico, un subsitio, una biblioteca de documentos, una carpeta o un único archivo
• Ingesta por lotes y en streaming mediante spark.read, Auto Loader y COPY INTO
• Inferencia y evolución automáticas de esquemas para formatos estructurados y semiestructurados, como CSV y Excel
• Almacenamiento seguro de credenciales con una conexión de Catálogo de Unity
• Selección de archivos con coincidencia de patrones mediante pathGlobFilter

Requisitos

Para ingerir archivos de SharePoint, debe tener lo siguiente:

• Un área de trabajo con Unity Catalog habilitado.
• CREATE CONNECTION privilegios para crear una conexión de SharePoint o el privilegio adecuado para usarla si ya existe, según su modo de acceso de clúster:
  • Modo de acceso dedicado: MANAGE CONNECTION.
  • Modo de acceso estándar: USE CONNECTION.
• Proceso que usa Databricks Runtime versión 17.3 LTS o posterior.
• La autenticación de OAuth se configura con el alcance de permiso Sites.Read.All o Sites.Selected.
• La característica beta de SharePoint está habilitada desde la página Previews. Consulte Administrar versiones preliminares de Azure Databricks.
• Opcional: habilite la característica beta de Excel para analizar archivos Excel. Consulte archivos de Excel.

Creación de la conexión

Cree una conexión de Catálogo de Unity para almacenar las credenciales de SharePoint. El proceso de configuración de conexión se comparte entre los conectores de SharePoint estándar y administrados.

Para obtener instrucciones de configuración de conexión completas, incluidas las opciones de autenticación de OAuth, consulte Información general sobre la configuración de ingesta de SharePoint.

Leer archivos de SharePoint

Para leer archivos, pase la conexión que creó con la opción databricks.connection y una dirección URL que apunte al recurso de SharePoint al que desea acceder. La dirección URL que proporcione determina el ámbito de la ingesta.

Los siguientes tipos de ruta de acceso se admiten en Databricks Runtime 17.3 LTS y versiones posteriores:

Databricks Runtime 18.3 y versiones posteriores agrega compatibilidad con los siguientes tipos de ruta de acceso:

Examples

Hay varias maneras de leer archivos mediante el conector estándar SharePoint.

Transmitir archivos de SharePoint mediante el Cargador Automático

Auto Loader proporciona la manera más eficaz de ingerir archivos estructurados de forma incremental desde SharePoint. Detecta automáticamente nuevos archivos y los procesa a medida que llegan. También puede ingerir archivos estructurados y semiestructurados, como CSV y JSON, con inferencia y evolución automáticas de esquemas. Para más información sobre el uso del cargador automático, consulte Patrones comunes de carga de datos.

# Incrementally ingest new PDF files
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("cloudFiles.schemaLocation", <path to a schema location>)
    .option("pathGlobFilter", "*.pdf")
    .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
)

# Incrementally ingest CSV files with automatic schema inference and evolution
df = (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "csv")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("pathGlobFilter", "*.csv")
    .option("inferColumnTypes", True)
    .option("header", True)
    .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs")
)

Leer archivos de SharePoint mediante la lectura por lotes de Spark

En el ejemplo siguiente se muestra cómo ingerir archivos SharePoint en Python mediante la función spark.read.

# Read unstructured data as binary files
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("recursiveFileLookup", True)
        .option("pathGlobFilter", "*.pdf") # optional. Example: only ingest PDFs
        .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents"))

# Read a batch of CSV files, infer the schema, and load the data into a DataFrame
df = (spark.read
        .format("csv")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("pathGlobFilter", "*.csv")
        .option("recursiveFileLookup", True)
        .option("inferSchema", True)
        .option("header", True)
        .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs"))

# Read a specific Excel file from SharePoint, infer the schema, and load the data into a DataFrame
df = (spark.read
        .format("excel")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("headerRows", 1)                   # optional
        .option("dataAddress", "Sheet1!A1:M20")  # optional
        .load("https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx"))

Leer archivos de SharePoint mediante Spark SQL

En el ejemplo siguiente se muestra cómo ingerir archivos SharePoint en SQL mediante la función con valores de tabla read_files. Para obtener más información sobre el read_files uso, consulte read_files función con valores de tabla.

-- Read pdf files
CREATE TABLE my_table AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  pathGlobFilter => "*.pdf", -- optional. Example: only ingest PDFs
  schemaEvolutionMode => "none"
);

-- Read a specific Excel sheet and range
CREATE TABLE my_sheet_table AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx",
  `databricks.connection` => "my_sharepoint_conn",
  format => "excel",
  headerRows => 1,  -- optional
  dataAddress => "Sheet1!A2:D10", -- optional
  schemaEvolutionMode => "none"
);

Ingesta incremental con COPY INTO

COPY INTO proporciona carga incremental idempotente de archivos en una tabla Delta. Para más información sobre el COPY INTO uso, consulte Patrones comunes de carga de datos mediante COPY INTO.

CREATE TABLE IF NOT EXISTS sharepoint_pdf_table;
CREATE TABLE IF NOT EXISTS sharepoint_csv_table;
CREATE TABLE IF NOT EXISTS sharepoint_excel_table;

# Incrementally ingest new PDF files
COPY INTO sharepoint_pdf_table
  FROM "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents"
  FILEFORMAT = BINARYFILE
  PATTERN = '*.pdf'
  FORMAT_OPTIONS ('databricks.connection' = 'my_sharepoint_conn')
  COPY_OPTIONS ('mergeSchema' = 'true');

# Incrementally ingest CSV files with automatic schema inference and evolution
COPY INTO sharepoint_csv_table
  FROM "https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs"
  FILEFORMAT = CSV
  PATTERN = '*.csv'
  FORMAT_OPTIONS ('databricks.connection' = 'my_sharepoint_conn', 'header' = 'true', 'inferSchema' = 'true')
  COPY_OPTIONS ('mergeSchema' = 'true');

# Ingest a single Excel file
COPY INTO sharepoint_excel_table
  FROM "https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx"
  FILEFORMAT = EXCEL
  FORMAT_OPTIONS ('databricks.connection' = 'my_sharepoint_conn', 'headerRows' = '1')
  COPY_OPTIONS ('mergeSchema' = 'true');

Ingestar archivos de SharePoint en canalizaciones declarativas de Spark de Lakeflow

En los ejemplos siguientes se muestra cómo leer archivos de SharePoint mediante Auto Loader en las canalizaciones declarativas de Lakeflow Spark.

Python

from pyspark import pipelines as dp

# Incrementally ingest new PDF files
@dp.table
def sharepoint_pdf_table():
  return (spark.readStream.format("cloudFiles")
    .option("cloudFiles.format", "binaryFile")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("pathGlobFilter", "*.pdf")
    .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
  )

# Incrementally ingest CSV files with automatic schema inference and evolution
@dp.table
def sharepoint_csv_table():
  return (spark.readStream.format("cloudFiles")
      .option("cloudFiles.format", "csv")
      .option("databricks.connection", "my_sharepoint_conn")
      .option("pathGlobFilter", "*.csv")
      .option("inferColumnTypes", True)
      .option("header", True)
      .load("https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs")
  )

# Read a specific Excel file from SharePoint in a materialized view
@dp.table
def sharepoint_excel_table():
  return (spark.read.format("excel")
    .option("databricks.connection", "my_sharepoint_conn")
    .option("headerRows", 1)                   # optional
    .option("inferColumnTypes", True)            # optional
    .option("dataAddress", "Sheet1!A1:M20")  # optional
    .load("https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx")

SQL

-- Incrementally ingest new PDF files
CREATE OR REFRESH STREAMING TABLE sharepoint_pdf_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  format => "binaryFile",
  `databricks.connection` => "my_sharepoint_conn",
  pathGlobFilter => "*.pdf");

-- Incrementally ingest CSV files with automatic schema inference and evolution
CREATE OR REFRESH STREAMING TABLE sharepoint_csv_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant.sharepoint.com/sites/Engineering/Data/IoT_Logs",
  format => "csv",
  `databricks.connection` => "my_sharepoint_conn",
  pathGlobFilter => "*.csv",
  "header", "true");

-- Read a specific Excel file from SharePoint in a materialized view
CREATE OR REFRESH MATERIALIZED VIEW sharepoint_excel_table
AS SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Finance/Shared%20Documents/Monthly/Report-Oct.xlsx",
  `databricks.connection` => "my_sharepoint_conn",
  format => "excel",
  headerRows => 1,  -- optional
  dataAddress => "Sheet1!A2:D10", -- optional
  `cloudFiles.schemaEvolutionMode` => "none"
);

Análisis de archivos no estructurados

Al ingerir archivos no estructurados de SharePoint (como archivos PDF, documentos Word o archivos PowerPoint) mediante el conector estándar de SharePoint con formato binaryFile, el contenido del archivo se almacena como datos binarios sin procesar. Para preparar estos archivos para cargas de trabajo de INTELIGENCIA ARTIFICIAL (como RAG, búsqueda, clasificación o comprensión de documentos), puede analizar el contenido binario en una salida estructurada y consultable mediante ai_parse_document.

En el ejemplo siguiente se muestra cómo analizar documentos no estructurados almacenados en una tabla delta de bronce denominada documents, agregando una nueva columna con contenido analizado:

CREATE TABLE documents AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  pathGlobFilter => "*.{pdf,docx}",
  schemaEvolutionMode => "none"
);
SELECT *, ai_parse_document(content) AS parsed_content
FROM documents;

La parsed_content columna contiene texto extraído, tablas, información de diseño y metadatos que se pueden usar directamente para canalizaciones de IA de bajada.

Análisis incremental con canalizaciones declarativas de "Lakeflow Spark"

También puede usar ai_parse_document en Canalizaciones declarativas de Lakeflow Spark para habilitar el análisis incremental. A medida que los nuevos archivos se transmiten desde SharePoint, se analizan automáticamente a medida que se actualiza la canalización.

Por ejemplo, puede definir una vista materializada que analice continuamente los documentos recién ingeridos:

CREATE OR REFRESH STREAMING TABLE sharepoint_documents_table
AS SELECT * FROM STREAM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  format => "binaryFile",
  `databricks.connection` => "my_sharepoint_conn",
  pathGlobFilter => "*.{pdf,docx}");

CREATE OR REFRESH MATERIALIZED VIEW documents_parsed
AS
SELECT *, ai_parse_document(content) AS parsed_content
FROM sharepoint_documents_table;

Este enfoque garantiza que:

• Los archivos de SharePoint recién ingeridos se analizan automáticamente cada vez que se actualiza la vista materializada.
• Las salidas analizadas permanecen sincronizadas con los datos entrantes
• Las canalizaciones de IA descendentes siempre funcionan con representaciones actualizadas de documentos.

Más información: consulte ai_parse_document para conocer los formatos admitidos y las opciones avanzadas.

columna de metadatos de SharePoint

La columna _sharepoint_metadata es una columna de metadatos oculta que proporciona acceso a propiedades específicas SharePoint de archivos ingeridos, procedentes del recurso driveItem Microsoft Graph. Requiere Databricks Runtime 18.1 o superior y está disponible para todos los formatos de archivo al leer desde SharePoint. Para incluir la _sharepoint_metadata columna en el dataframe devuelto, debe seleccionarla explícitamente en la consulta de lectura.

Si el origen de datos contiene una columna denominada _sharepoint_metadata, se cambia el nombre de la columna de metadatos de SharePoint a __sharepoint_metadata (con un carácter de subrayado inicial adicional) para desduplicar. Se agregan caracteres de subrayado adicionales hasta que el nombre es único.

Los metadatos de archivo comunes, como la ruta de acceso o el tamaño del archivo, se pueden consultar mediante la _metadata columna . Para obtener más información, consulte Columna de metadatos de archivo.

Esquema

La _sharepoint_metadata columna es un STRUCT que contiene los siguientes campos. Todos los campos admiten valores NULL.

Ejemplos

En los ejemplos siguientes se muestra cómo incluir la _sharepoint_metadata columna en una consulta de lectura, seleccionar campos específicos de la columna y extraer valores del additional_metadataVARIANT campo.

Python

df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
        .select("*", "_metadata", "_sharepoint_metadata"))

SQL

SELECT *, _sharepoint_metadata
FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile"
);

Seleccione campos específicos en la _sharepoint_metadata estructura:

df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .load("https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents")
        .select("_sharepoint_metadata.item_id", "_sharepoint_metadata.etag"))

Extraiga valores del campo additional_metadataVARIANT mediante el operador de conversión ::.

SELECT
  *,
  _sharepoint_metadata.additional_metadata:shared:scope::STRING AS shared_scope
FROM read_files(
  "https://mytenant.sharepoint.com/sites/Marketing/Shared%20Documents",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile"
);

Limitaciones

El conector SharePoint estándar tiene las siguientes limitaciones.

• Sin ingestión de múltiples sitios: no se pueden ingerir varios sitios con la misma consulta. Para recopilar datos de dos sitios, debe escribir dos consultas separadas.
• Filtrado: puede usar la pathGlobFilter opción para filtrar los archivos por nombre. No se admite el filtrado basado en la ruta de acceso de carpeta.
• No se admiten formatos compatibles: no se admiten SharePoint listas y páginas de sitio de .aspx. Solo se admiten archivos en bibliotecas de documentos.
• No se admite la escritura en un servidor de SharePoint.
• No se admite el cargador cleanSource automático (eliminación o archivado de archivos en el origen después de la ingesta).

Pasos siguientes

• Más información sobre Auto Loader para patrones avanzados de ingesta de streaming
• Explora COPY INTO para cargas incrementales idempotentes
• Comparación con los patrones de ingesta de almacenamiento de objetos en la nube
• Configura la programación de trabajos para automatizar los flujos de trabajo de ingestión
• Uso de Lakeflow Spark Declarative Pipelines para crear canalizaciones de datos de extremo a extremo con transformaciones