Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Use Azure Content Understanding to extract and enrich SharePoint documents in Foundry IQ (Azure AI Search). This guidance applies to the SharePoint in Microsoft 365 indexer and SharePoint (indexed) knowledge sources.
Built-in parsing provides text extraction and works with other AI enrichment skills. For layout-rich or multimodal documents, Content Understanding combines layout-aware parsing, chunking, and image extraction in one skill. It also generates optional image descriptions, using a deployed model.
Supported inputs include Microsoft Word (DOCX) documents, Microsoft Excel (XLSX) workbooks, and Microsoft PowerPoint (PPTX) presentations, subject to format-specific restrictions. Use the knowledge source APIs with contentExtractionMode: "standard" for simpler setup and lifecycle operations. For more control over skills, chunking, and projections, configure a SharePoint indexer and Content Understanding skillset directly.
Prerequisites
- A Foundry IQ service, with permission to create Search objects and query them. For the knowledge-source paths, use a region that supports agentic retrieval. See Search role-based access for the applicable management and data roles.
- Completion of the SharePoint indexer prerequisites and authentication setup. For permission ingestion, follow the ACL prerequisites, not a delegated-authentication example.
- A Microsoft Foundry resource in a Content Understanding-supported region. When configuring an indexer and skillset directly, configure the Search managed identity, required roles, and skillset resource attachment.
- An embedding deployment when vectorization is required. For optional built-in image descriptions, a supported description-model deployment in the attached Foundry resource.
- Representative files supported by both the SharePoint indexer and the Content Understanding skill, including the layouts and figures you expect to retrieve.
Choose an extraction pipeline
Choose the pipeline based on the processing you need and the resources you intend to maintain.
| Pipeline | Use it when | Resource ownership |
|---|---|---|
| Knowledge source API configuration | You want simpler setup through one SharePoint (indexed) knowledge source configuration. | Search generates the indexer, data source, skillset, and index. Use knowledge source settings and lifecycle operations to maintain them. |
| Indexer and skillset configuration | You need more control over skills, chunking, or projections than the knowledge source settings expose. | You configure and maintain the ingestion objects and secured index directly. Add a search index knowledge source if you want to use the index in a knowledge base. |
The two paths have the following shape. In both paths, model traffic is separate from the SharePoint source connection:
Knowledge source APIs: SharePoint documents → generated indexer → Content Understanding semantic chunking and image descriptions → embedding skill → generated secured chunk index → SharePoint (indexed) knowledge source → knowledge base.
Indexer and skillset APIs: SharePoint documents → your indexer → Content Understanding semantic chunking and image descriptions → embedding skill (for vector search) → your secured chunk index. Query the index directly, or connect it to a knowledge base through a search index knowledge source.
Enrichment connections: Content Understanding skill → attached Foundry resource for analysis and optional built-in descriptions; embedding skill → embedding endpoint and deployment.
For indexed knowledge sources, minimal extraction uses built-in parsing. Use it for text-first extraction or when separate enrichment skills provide the processing you need. Choose standard extraction to combine Content Understanding's layout-aware parsing, chunking, image extraction, and optional descriptions in a generated pipeline.
When configuring an indexer directly, add the Content Understanding skill to your skillset for the same integrated document-processing capabilities. You still configure embeddings and any additional enrichment separately.
Keep the processing stages distinct:
- Layout extraction identifies document structure, including sections, tables, and figures. Validate the extracted structure with representative files in your supported formats.
- Chunking prepares content spans. Semantic chunking follows layout and paragraph boundaries; fixed-size chunking uses character windows. Neither choice alone enables descriptions.
- Image extraction produces image data and references. Descriptions add generated text for applicable figures.
- Embeddings represent chunk content as vectors. Image serving makes images available at retrieval time through a separately supported configuration; an extracted image reference isn't a downloadable URL.
For retrieval directly from SharePoint instead of an indexed pipeline, see the SharePoint (remote) knowledge source, which has a different retrieval and permissions architecture.
Use standard extraction in a SharePoint (indexed) knowledge source
Standard extraction uses Content Understanding to parse supported documents and prepare semantic chunks in a generated pipeline. Configure permissions and an image-description model on the knowledge source. Search creates the underlying data source, indexer, Content Understanding skillset, and secured chunk index.
- Follow Create an indexed SharePoint knowledge source for the connection, source selection, identities, and embedding model.
- In
indexedSharePointParameters.ingestionParameters, configure the following standard-extraction settings:- Set
contentExtractionModetostandard. - Set
ingestionPermissionOptionsto["userIds", "groupIds"]to preserve SharePoint document permissions. - Configure
aiServiceswith your supported Foundry resource endpoint.
- Set
- Configure
chatCompletionModelwith the supported image-description model and deployment in that Foundry resource. LeavedisableImageVerbalizationset tofalseor omit it. Review the canonical image description controls for configuration requirements. - Configure
embeddingModel.azureOpenAIParameterswith your Foundry resource endpoint inresourceUri, plus the embeddingdeploymentIdandmodelName. For example, usehttps://<embedding-resource>.services.ai.azure.comfor the endpoint. The generated embedding skill vectorizes Content Understanding's chunk content, including generated image descriptions, before indexing. - Run ingestion and review the generated objects, including permissions on projected chunks.
- After ingestion succeeds, the knowledge source is ready to assign to a knowledge base. You don't need a separate search index knowledge source for this path.
Content Understanding semantic chunking and image descriptions are generally available in Search REST API 2026-10-01. SharePoint connector and permission features retain their separately documented availability and API requirements. The downstream Content Understanding API version is documented separately.
Limit this file-processing path to supported documents. SharePoint list items and site pages parsed as text don't provide the original file input required by Content Understanding. Don't assume that a library-file configuration applies unchanged to mixed-content selections.
Configure a SharePoint indexer and Content Understanding skillset
Use the indexer and skillset APIs for more control over your enrichment pipeline. Connect your SharePoint indexer to a Content Understanding skill that performs semantic chunking and image verbalization. Configure the skillset and mappings to write enriched chunks and their SharePoint permissions to your index.
- Configure the data source by using the SharePoint indexer procedure. Preserve source permissions by setting
indexerPermissionOptionsto["userIds", "groupIds"]in the data source. Follow the SharePoint ACL configuration for authentication and permission-filter fields in the index. - On the indexer, set
parameters.configuration.allowSkillsetToReadFileDatatotrue. This setting exposes the original file at/document/file_datafor the Content Understanding skill'sfile_datainput. Use the original file, not text already extracted into/document/content. - Add the Content Understanding skill with semantic chunking and image descriptions to your skillset:
- Set
chunkingProperties.methodtosemanticandchunkingProperties.unittotokens. - Set both
modelNameandmodelDeploymentto use your supported image-description model in the attached Foundry resource. - Include
imagesandlocationMetadatainextractionOptionsfor image extraction and location outputs. - Map
file_datato/document/file_dataand retain thetext_sectionsoutput. Generated descriptions are included in each applicable chunk's Markdown content.
- Set
- For vector search, add an embedding skill after the Content Understanding skill:
- Set
resourceUrito your Foundry resource endpoint, such ashttps://<embedding-resource>.services.ai.azure.com, and configuredeploymentIdandmodelName. - Set the skill's
contextto/document/text_sections/*and itstextinput to/document/text_sections/*/content. This setup embeds each Content Understanding chunk after its image descriptions are included. - Map the
embeddingoutput totext_vector. Align vector dimensions with the index and configure a compatible query-time vectorizer.
- Set
- Define one-to-many index projections with
sourceContextset to/document/text_sections/*. Project the chunk content,/document/text_sections/*/text_vectorwhen configured, source and citation fields, and requested location metadata into the chunk index. - Follow the SharePoint permission-projection requirements to repeat the parent document's permissions on every chunk:
- Map
/document/metadata_user_idsto the index'sUserIdspermission field. - Map
/document/metadata_group_idsto the index'sGroupIdspermission field. - For SharePoint site groups, also project
/document/metadata_spo_site_urltoSharePointSiteUrland configure the required SharePoint group resolution. - When using
projectionMode: skipIndexingParentDocuments, use these projection mappings rather than relying only on indexer field mappings.
- Map
- Run the indexer and inspect the enriched chunks and permissions in your index. To use the index in a knowledge base, also configure the fields and semantic configuration in the index criteria for agentic retrieval.
Content Understanding supplies chunking and built-in image descriptions in this pipeline; you don't need a separate Text Split or Chat Completion skill for those operations. For the skill's input/output relationships, see the Content Understanding walkthrough. Keep your SharePoint source and permission configuration; don't copy the walkthrough's Blob connection or optional image-storage step.
Keep permission metadata out of skill and model inputs. Carry it through source-level projection mappings instead. Don't substitute a Custom Web API skill to bypass a protected-content restriction.
Preserve permissions and verify retrieval
Permission filtering must survive chunking and retrieval. Use the canonical permission fields and mappings for user IDs, group IDs, and applicable site context. Preserve required source-path metadata as well as readable citation information. Keep permission fields nonretrievable in normal queries.
If you configure the indexer and skillset directly, you can query the resulting index with Search. To use that index in a knowledge base, follow Create a search index knowledge source, then assign it to a knowledge base. This handoff uses the existing index; it doesn't ingest SharePoint content or rerun Content Understanding. For the knowledge source API configuration, assign the SharePoint (indexed) knowledge source itself to the knowledge base.
Before using either pipeline in production:
- Inspect representative chunks for content, vectors when configured, source/citation associations, and required permission mappings.
- Test direct Search queries with permitted and denied users using the query-time permission procedure. If you use a knowledge base, also test its retrieve requests with those users.
- If your application exposes an MCP endpoint, test its user-token propagation and access results too. Check that returned citations and source-data fields don't reveal denied content.
- Test applicable group and site scenarios and permission revocation using the SharePoint synchronization guidance. Indexing success alone doesn't prove current authorization.
Review networking and resource ownership
Treat inbound application access to Search separately from outbound ingestion. A private endpoint for Search doesn't establish private connectivity to SharePoint, Content Understanding, or model deployments.
- SharePoint source: Use the connector's authentication contract. SharePoint Online uses public endpoints and isn't a shared private link target.
- Content Understanding analysis: Use the attached supported Foundry resource and its required identity and connectivity.
- Embeddings and optional chat: Check each configured endpoint's supported authentication, role assignments, DNS, and network access requirements.
A separate GenAI Prompt (Chat Completion) or custom endpoint doesn't proxy Content Understanding analyzer calls. API Management isn't supported for Content Understanding. For ACL-only ingestion, a separate Chat Completion skill requires a permitted first-party endpoint, not APIM. With sensitivity-label ingestion, that Chat Completion configuration isn't supported.
Apply the canonical protected-content limitations to the specific configuration, including Custom Web API, cache, knowledge-store, debug, and image-serving restrictions. Authentication or private routing doesn't make a blocked configuration supported.
You maintain the pipeline objects you create directly. For wizard-created objects, use the documented workflow for that wizard. For objects generated by a knowledge source, use knowledge source settings and lifecycle operations; don't treat generated objects as an unrestricted customization surface.
Troubleshoot processing and maintain the pipeline
For missing Content Understanding output or slow processing, follow the guidance in analysis polling and large-document guidance. The default analysis-poll window is eight minutes. Custom-analyzer readiness has a separate five-minute window. Inspect indexer status to distinguish polling expiration from authentication, throttling, input-format, or terminal service failures.
Use the SharePoint permission lifecycle procedures for refresh, resynchronization, revocation, and supported rebuild operations. Don't use a content reset as a substitute for understanding permission-refresh behavior.
When retiring a pipeline, stop its schedule and use its documented deletion procedure. Remove customer-owned objects only when they're no longer needed. Deleting a Search knowledge source doesn't delete external SharePoint content, Foundry resources, or model deployments.