Microsoft SharePoint 노드를 사용하면 Microsoft SharePoint에서 작업을 자동화하고 Microsoft SharePoint를 다른 애플리케이션과 통합할 수 있습니다. n8n은 파일 다운로드, 업로드, 업데이트, 목록의 항목 관리, 목록 및 목록 항목 조회를 포함한 다양한 Microsoft SharePoint 기능을 기본으로 지원합니다.

이 페이지에서는 Microsoft SharePoint 노드가 지원하는 작업 목록, 로그인 방법과 사이트 선택 안내, 노드 버전 2에서 달라진 점, 추가 참고 자료 링크를 확인할 수 있습니다.

로그인 방식 선택#

두 로그인 방식 모두 모든 작업을 지원합니다. 워크플로가 실행되는 방식에 따라 선택합니다.

작업#

• File(파일):
  • Download(다운로드): 파일을 다운로드합니다.
  • Update(업데이트): 파일 이름을 바꾸거나, 내용을 교체하거나, 둘 다 수행합니다.
  • Upload(업로드): 문서 라이브러리에 파일을 업로드합니다.
• Item(항목):
  • Create(생성): 기존 목록에 항목을 생성합니다.
  • Create or Update(생성 또는 업데이트): 새 항목을 생성하거나, 이미 존재하는 경우 현재 항목을 업데이트합니다(upsert).
  • Delete(삭제): 목록에서 항목을 삭제합니다.
  • Get(조회): 목록에서 항목을 조회합니다.
  • Get Many(다수 조회): 목록에서 특정 항목들을 가져오거나 여러 항목을 조회합니다.
  • Update(업데이트): 기존 목록의 항목을 업데이트합니다.
• List(목록):
  • Get(조회): 단일 목록의 세부 정보를 조회합니다.
  • Get Many(다수 조회): 목록들의 리스트를 조회합니다.

사이트 선택#

모든 작업은 Site에서 시작합니다. 다음 세 가지 방법 중 하나로 설정합니다.

• From List: 조직의 사이트를 이름으로 검색합니다. 사이트 검색에는 테넌트 전체 읽기 권한(Sites.Read.All 또는 Sites.ReadWrite.All)이 필요하며, 사이트별 접근에서는 사용할 수 없습니다.
• By URL: 전체 사이트 주소를 붙여 넣습니다. 예: https://contoso.sharepoint.com/sites/mysite.
• By ID: Microsoft Graph 문서에 정의된 형식 중 어느 것으로든 사이트 ID를 붙여 넣습니다. 사이트 선택기와 Graph가 반환하는 복합 ID(contoso.sharepoint.com,<site-GUID>,<web-GUID>), 사이트 GUID만, 호스트 이름(테넌트 루트 사이트), 또는 root를 사용할 수 있습니다. 사이트의 복합 ID를 찾으려면 주소로 요청합니다. GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/mysite

사이트별 접근#

일부 조직은 앱에 SharePoint에 대한 테넌트 전체 접근 권한을 부여하지 않습니다. 대신 Sites.Selected 권한을 사용하고 앱에 개별 사이트에 대한 접근 권한을 부여합니다. 노드는 이 방식을 완전히 지원합니다. 테넌트 전체 읽기 권한 없이는 Microsoft Graph가 지원하지 않는 사이트 검색을 제외하고, 모든 작업과 선택기가 동작합니다. 대신 Site 필드를 By URL 또는 By ID로 설정합니다. 두 방식 모두 검색이 필요하지 않습니다.

사이트별 접근을 설정하는 방법은 다음과 같습니다.

• 앱으로 로그인하는 경우: 앱 등록에 Sites.Selected 애플리케이션 권한을 부여하고 관리자 동의를 받은 다음, 각 사이트에서 앱에 read 또는 write 접근 권한을 부여합니다. 사이트별 접근 권한 부여를 참고하거나, 권한 매니페스트를 포함해 복사하여 붙여 넣을 수 있는 설정은 Azure CLI로 SharePoint 앱 등록 프로비저닝을 참고하세요.
• 사용자로 로그인하는 경우: 자격 증명의 Scope 필드를 openid offline_access Sites.Selected로 설정합니다. 앱 등록에는 동일한 사이트별 권한 부여가 적용되며, 로그인한 계정도 해당 사이트에 대한 접근 권한이 필요합니다.

버전 1에서 달라진 점#

버전 2는 Microsoft Graph API를 기반으로 노드를 다시 구축한 것입니다. 기존 워크플로는 만들 당시의 버전을 유지하므로, 새 노드를 추가하거나 워크플로를 버전 2로 전환하기 전까지는 아무것도 바뀌지 않습니다. 전환하면 다음과 같이 달라집니다.

• 자격 증명이 바뀝니다. 버전 2는 범용 Microsoft OAuth2 자격 증명으로 로그인하거나, 버전 2에서 새로 추가되어 사용자가 없는 앱 전용 무인 워크플로에 쓰는 Microsoft Entra Service Principal 자격 증명으로 로그인합니다. 버전 1의 Microsoft SharePoint 자격 증명은 버전 2에서 제공되지 않습니다. 이 자격 증명의 토큰은 이전 SharePoint REST API를 대상으로 하므로 Microsoft Graph에서는 실패합니다. 버전 1 워크플로는 이 자격 증명을 변경 없이 계속 사용합니다.
• 항목 업데이트는 Microsoft가 문서화한 경로를 사용합니다. 버전 1은 동작은 하지만 Microsoft 문서에 없는 경로로 항목을 업데이트했습니다. 버전 2는 문서화된 Microsoft Graph 엔드포인트로 업데이트를 전송하고 이전과 동일한 출력을 반환하므로 워크플로에서는 차이를 느끼지 못합니다. 또한 버전 2는 일치 칼럼이 둘 이상의 항목을 식별할 때 더 엄격하게 처리합니다. 버전 1의 Create or Update는 중복 항목을 생성했지만, 버전 2에서는 Update와 Create or Update 모두 명확한 오류와 함께 중단됩니다.
• 파일 다운로드는 먼저 다운로드 링크를 가져옵니다. 버전 2는 Microsoft Graph에 파일의 메타데이터와 사전 승인된 단기 다운로드 링크를 요청한 다음, 그 링크에서 콘텐츠를 가져옵니다. 링크가 이미 승인되어 있으므로 n8n은 링크 요청에 로그인 정보를 첨부하지 않습니다. 다운로드한 파일은 이름을 포함해 버전 1과 동일합니다.

일반적인 문제#

• 사이트별 권한에서 사이트 검색이 실패합니다. Microsoft Graph는 사이트별 접근 권한만 있는 자격 증명으로는 사이트를 나열할 수 없습니다. Site 필드를 By URL 또는 By ID 모드로 전환하거나, 검색이 필요하면 테넌트 전체 읽기 권한(Sites.Read.All 또는 Sites.ReadWrite.All)을 부여하세요.
• 403 오류가 누락된 권한을 지목합니다. 노드의 권한 오류는 작업에 필요한 Microsoft Graph 권한의 이름을 알려 줍니다. 예: Sites.ReadWrite.All (or Sites.Selected granted with write access for this site). 애플리케이션 권한은 관리자 동의와 함께 해당 권한을 부여한 다음 다시 시도하세요. 사이트별 접근을 사용하는 경우에는 사용 중인 사이트에 대한 접근 권한이 앱에 부여되었는지도 확인하세요.
• Service Principal 자격 증명 테스트는 통과하지만 작업이 실패합니다. n8n 2.40.0부터 연결 테스트는 앱 등록이 로그인할 수 있는지만 확인하며, 앱 등록이 어떤 권한을 가지고 있는지는 확인하지 않습니다. SharePoint 애플리케이션 권한에 관리자 동의가 있는지, 사이트별 접근을 사용하는 경우 앱에 해당 사이트에 대한 접근 권한이 부여되었는지 확인하세요. Microsoft Entra Service Principal 자격 증명 문서를 참고하세요.
• 자격 증명 연결이 AADSTS 오류 코드와 함께 실패합니다. Microsoft가 로그인 또는 토큰 교환을 거부했습니다. 예: AADSTS7000215(잘못된 클라이언트 시크릿), AADSTS7000222(만료된 클라이언트 시크릿), AADSTS700027(거부된 인증서 어설션). Microsoft Entra Service Principal 자격 증명 문서의 일반적인 문제를 참고하세요.
• 250MB를 넘는 업로드가 실패합니다. File: Upload와 File: Update는 콘텐츠를 단일 요청으로 전송하며, 이 요청은 250MB로 제한됩니다. 더 큰 파일을 나누어 업로드하는 기능은 아직 지원되지 않습니다.
• 큰 목록 필터링이 실패합니다. SharePoint는 항목이 5,000개를 넘는 목록을 인덱싱된 칼럼에 대해서만 필터링합니다. SharePoint에서 인덱스를 추가하거나(List settings > Indexed columns) 인덱싱된 칼럼으로 필터링하세요.
• 항목 생성 또는 업데이트가 고유 제약 조건 오류로 실패합니다. 목록의 칼럼이 고유한 값을 강제하는데, 입력하려는 값이 다른 항목에 이미 존재합니다. 값을 변경하거나, SharePoint에서 해당 칼럼의 Enforce unique values 설정을 해제하세요.

템플릿 및 예제#

Microsoft SharePoint 노드 문서 통합 템플릿 둘러보기 또는 전체 템플릿 검색

관련 자료#

노드 버전 2는 Microsoft Graph API를 사용합니다. 이 서비스에 대한 자세한 내용은 Microsoft의 SharePoint용 Graph 문서를 참고하세요. 버전 1은 SharePoint REST API를 사용합니다.