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 SharePoint. Ambos acceden a los datos en SharePoint, pero difieren en su nivel de administración.

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 de páginas de sitios de SharePoint (.aspx) en Databricks Runtime 19 y versiones posteriores. Consulte Ingesta de páginas de sitios de SharePoint.
• 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.
• Cómputo que utiliza Databricks Runtime versión 17.3 LTS o superior.
• La autenticación de OAuth se configura con el alcance de permiso Sites.Read.All o Sites.Selected.
• Opcional: habilite la característica beta de Excel para analizar archivos Excel. Consulte Leer y transmitir archivos 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 son compatibles con Databricks Runtime 17.3 LTS y superiores:

Databricks Runtime 18 LTS y superiores añade soporte para los siguientes tipos de rutas:

Databricks Runtime 19 y superiores añade soporte para los siguientes tipos de rutas:

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-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("cloudFiles.schemaLocation", "<path-to-schema-location>")
    .option("pathGlobFilter", "*.csv")
    .option("cloudFiles.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. Establece la opción recursiveFileLookup en true para leer archivos de estructuras anidadas, como bibliotecas de documentos en un sitio, carpetas en una biblioteca de documentos o subsitios en un sitio.

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

Ingesta de archivos SharePoint en canalizaciones de Lakeflow

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

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("cloudFiles.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, map('version', '2.0')) 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 las canalizaciones de Lakeflow

También puede usar ai_parse_document dentro de las canalizaciones de Lakeflow 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, puedes definir una tabla de streaming bronce que ingiere los archivos binarios en bruto, y luego una segunda tabla de streaming que asigne el contenido analizado a una nueva columna:

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 STREAMING TABLE documents_parsed
AS SELECT
  *,
  ai_parse_document(content, map('version', '2.0')) AS parsed_content
FROM STREAM sharepoint_documents_table;

Este enfoque garantiza que:

• Los archivos de SharePoint recién incorporados se analizan automáticamente cada vez que la canalización se actualiza.
• Las salidas analizadas se mantienen sincronizadas con los datos entrantes.
• Las canalizaciones de IA aguas abajo siempre trabajan con representaciones de documentos actualizadas.

Consulta la ai_parse_documentfunción para ver los formatos admitidos y las opciones avanzadas, incluida la opción version, que fija el esquema de salida.

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 LTS 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.

Ejemplo

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

Ingestión de páginas de sitios de SharePoint

SharePoint almacena las Páginas del Sitio como .aspx archivos en la biblioteca de Páginas del Sitio de un sitio, separados de sus bibliotecas de documentos. La ingesta de páginas de sitios requiere Databricks Runtime 19 o una versión posterior. Para más información sobre las páginas del sitio, consulte las páginas de SharePoint y el modelo de página.

Puedes ingerir las Páginas del Sitio de las siguientes maneras:

Ingesta las páginas del sitio como cualquier otro archivo:

Python

# Read a single Site Page
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .load("https://mytenant.sharepoint.com/sites/test-site/SitePages/my-news-post.aspx"))

# Read a site's Site Pages library
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("pathGlobFilter", "*.aspx") # optional. Example: only ingest Site Page files
        .load("https://mytenant.sharepoint.com/sites/test-site/SitePages"))

# Read all Site Pages from a site
df = (spark.read
        .format("binaryFile")
        .option("databricks.connection", "my_sharepoint_conn")
        .option("recursiveFileLookup", True)
        .option("pathGlobFilter", "*.aspx") # optional. Example: only ingest Site Page files
        .load("https://mytenant.sharepoint.com/sites/test-site"))

SQL

-- Read a single Site Page
CREATE TABLE site_page AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/test-site/SitePages/my-news-post.aspx",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile"
);

-- Read a site's Site Pages library
CREATE TABLE site_pages AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/test-site/SitePages",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  pathGlobFilter => "*.aspx" -- optional. Example: only ingest Site Page files
);

-- Read all Site Pages from a site
CREATE TABLE site_with_pages AS
SELECT * FROM read_files(
  "https://mytenant.sharepoint.com/sites/test-site",
  `databricks.connection` => "my_sharepoint_conn",
  format => "binaryFile",
  recursiveFileLookup => true,
  pathGlobFilter => "*.aspx" -- optional. Example: only ingest Site Page files
);

Auto Loader, COPY INTO, y otras interfaces funcionan con las Páginas del Sitio igual que cualquier otro archivo. Consulta Ejemplos para ejemplos de ingestión.

Limitaciones

El conector SharePoint estándar tiene las siguientes limitaciones.

• No se pueden ingerir varios sitios con la misma consulta. Para recopilar datos de dos sitios, debe escribir dos consultas separadas.
• 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 soportan listas de SharePoint.
• 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
• Utiliza pipelines de Lakeflow para crear flujos de datos integrales con transformaciones