M365Con 2027 – 무료 온라인 컨퍼런스 · 11–22 Jan 2027 · 120 sessions→ m365con.net

블로그 · Mirko Peters

Microsoft Graph PowerShell으로 SharePoint 관리하기: 첫 번째 명령어

By · · Updated

SharePoint용 Microsoft Graph PowerShell: SDK 설치, 올바른 범위로 로그인, Get-MgSite로 사이트 목록 조회, 관리자가 가장 먼저 마주치는 403 오류 해결까지 정리합니다.

Automatically translated with AI from the original post. Read the English original

SharePoint용 Microsoft Graph PowerShell은 Graph SDK를 사용해 명령줄에서 사이트를 읽고 관리하는 방식을 말합니다. 모듈 하나를 설치하고, Connect-MgGraph와 권한 범위로 로그인한 뒤, Get-MgSite 같은 cmdlet을 실행하면 됩니다. 이 가이드는 SharePoint 관리 센터에 이미 익숙하고 안전하게 스크립팅을 시작하려는 SharePoint 관리자를 위한 것입니다. SDK를 설치하고, 동작하는 최소 범위로 로그인하고, 사이트를 조회하며, 처음 마주치는 오류를 읽는 방법을 익히게 됩니다.

핵심 포인트

  • Microsoft Graph PowerShell은 Graph API를 감싸는 SDK이므로, 모든 명령은 먼저 올바른 권한 범위로 Connect-MgGraph 로그인이 필요합니다.
  • Get-MgSite는 SharePoint 사이트를 조회하며, 최소한 Sites.Read.All 권한이 필요합니다. Microsoft가 이 명령에 대해 문서화한 가장 낮은 권한 옵션입니다.
  • Get-MgContext는 현재 세션이 가진 범위를 보여 주므로, 403 Forbidden 오류의 원인을 가장 빠르게 설명할 수 있는 방법입니다.
  • Find-MgGraphCommand와 Find-MgGraphPermission은 명령에 필요한 권한을 알려 주므로, 범위 이름을 추측할 필요가 없습니다.
  • 위임 로그인은 키보드 앞에 있는 사용자에게 적합하고, 인증서나 관리 ID를 사용하는 앱 전용 로그인은 무인 작업에 적합합니다.

Microsoft Graph PowerShell이란 무엇이며, 관리자가 이를 사용하는 이유

Microsoft Graph는 사용자, 그룹, 파일, 메일, Teams, SharePoint 사이트 등 Microsoft 365 데이터를 위한 단일 API입니다. Microsoft Graph PowerShell SDK는 Graph API를 cmdlet으로 감쌉니다. 엔드포인트마다 웹 요청을 직접 작성할 필요가 없습니다. Get-MgSite를 실행하면 사이트 개체가 반환됩니다.

SharePoint 관리자에게 이는 세 가지 실질적인 이점이 있습니다.

  • 서비스 전반에 걸친 하나의 도구. 사이트, 사용자, 그룹에 같은 로그인이 적용됩니다. 스크립트로 사이트를 조회한 다음 각 사이트의 소유자를 확인할 수 있습니다.
  • 이해하기 쉬운 권한 모델. 모든 호출에는 범위(scope)라고 부르는 명명된 권한이 필요합니다. 세션이 어떤 범위를 가졌는지, 그리고 호출이 왜 거부되었는지 확인할 수 있습니다.
  • 이전 모듈에서 벗어나는 경로. Microsoft Graph PowerShell 항목 설명에 따르면, 이 모듈은 지원이 종료된 Azure AD PowerShell 및 MSOnline 모듈의 대체 모듈입니다.

커뮤니티 PnP PowerShell 모듈도 SharePoint 스크립팅에서 흔히 선택하는 도구이며, 문서에 따르면 일부 cmdlet은 Graph와도 통신합니다. Graph PowerShell이 모든 SharePoint 관리 도구를 대체하는 것은 아닙니다. Graph API가 제공하는 범위만 다룹니다. 일부 테넌트 설정은 여전히 SharePoint 관리 센터나 다른 모듈에 있습니다. Graph는 유일한 도구가 아니라 도구 모음의 하나로 생각하세요.

1단계: SDK 설치 및 로그인

설치 가이드에서는 모든 플랫폼에서 PowerShell 7 이상을 권장합니다. Windows PowerShell은 버전 5.1 이상, .NET Framework 4.7.2 이상, 그리고 RemoteSigned 이하로 제한되지 않은 실행 정책이 필요합니다.

다음 단계를 따르십시오.

  1. 자신의 계정에 모듈을 설치하려면 다음 명령을 실행합니다: Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. 관리자 권한이 있고 공용으로 설치해야 할 때만 -Scope AllUsers를 사용합니다.
  2. Get-InstalledModule Microsoft.Graph로 설치 결과를 확인합니다.
  3. 기본 모듈은 47개가 넘는 하위 모듈을 함께 설치한다는 점을 알아 두십시오. 문서에 따르면 필요한 하위 모듈만 설치할 수 있으며, 이들과 함께 Microsoft.Graph.Authentication도 설치됩니다.
  4. 나중에는 Update-Module Microsoft.Graph로 업데이트합니다. 오래된 모듈은 버전 충돌의 원인으로 명시되어 있습니다.

한 PowerShell 버전에 설치해도 다른 버전에는 설치되지 않으므로, 사용할 버전에서 명령을 실행하십시오.

이제 로그인합니다. 인증 명령 문서에서는 SDK가 위임(delegated)과 앱 전용(app-only) 두 가지 액세스 유형을 지원한다고 설명합니다. 위임 액세스는 로그인한 사용자를 대신하며, 권한은 스코프로 지정합니다. 앱 전용 액세스는 사용자 없이 인증서, 클라이언트 비밀 또는 관리 ID로 실행됩니다.

처음 실행하는 명령에는 위임 액세스를 사용하고, 읽기 전용 스코프 하나만 요청하십시오:

Connect-MgGraph -Scopes "Sites.Read.All"

로그인용 브라우저 창이 열립니다. 어떤 권한을 받았는지 확인하려면 Get-MgContext | Select -ExpandProperty Scopes를 실행합니다. Microsoft 문서에 따르면 Get-MgContext는 클라이언트 ID, 테넌트 ID, 스코프, 인증 유형 등 현재 세션의 세부 정보를 반환하는 명령입니다. 작업이 끝나면 Disconnect-MgGraph를 실행합니다. 문서에서는 이를 실행하기 전까지 로그인 상태가 유지된다고 설명하는데, 토큰이 기본 CurrentUser 스코프에 캐시되기 때문입니다. 로그인을 현재 세션에서만 유지하려면 Connect-MgGraph에 -ContextScope Process를 추가합니다.

SharePoint 사이트를 위한 첫 명령

Get-MgSite 참조 문서에는 주요 매개 변수가 나와 있습니다. -Filter, -Search, -Property(별칭 -Select), -Top, -Sort, -All입니다. 문서의 예제는 간단합니다:

  • Get-MgSite는 사이트를 나열합니다.
  • Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"는 속성 두 개만 포함하여 루트 사이트 컬렉션만 반환합니다.

여기서부터 점차 확장해 보십시오:

  1. 페이징하여 나열합니다. Get-MgSite -All을 실행하면 모든 페이지의 결과를 가져옵니다. -All을 빼면 첫 페이지만 보일 수 있습니다.
  2. 열을 선택합니다. -Property "id,displayName,webUrl"을 추가하면 출력이 간결하고 읽기 쉬워집니다.
  3. 키워드로 검색합니다. Get-MgSite -Search "finance"를 실행합니다. Graph 검색 API는 여러 사이트 속성에서 자유 텍스트를 매칭합니다.
  4. 사이트 하나를 가져옵니다. Get-MgSite -SiteId <id>를 실행합니다. 여기서 ID는 이전 결과의 id 값이며, 호스트 이름과 쉼표로 구분된 GUID 두 개 형식입니다.

이 cmdlet은 각각 REST 호출에 대응합니다. Get-MgSite -All은 REST 문서에서 사이트 목록을 조회하는 URL인 https://graph.microsoft.com/v1.0/sites에서 sites 컬렉션을 읽으며, -Filter, -Search, -Property는 이 URL의 쿼리 옵션이 됩니다. SDK는 Microsoft Authentication Library(MSAL)를 통해 토큰을 얻습니다. 필요한 호출에 해당하는 cmdlet이 없으면 Invoke-MgGraphRequest로 URI를 직접 호출할 수 있습니다. 문제 해결 문서에서도 Bad request 오류의 원인이 되는 URI를 확인할 때 이 명령을 사용합니다.

두 가지 제한 사항을 짚어 두겠습니다. 첫째, Graph 목록 엔드포인트는 조직의 기본 지역(geography)에 있는 사이트만 반환합니다. 모든 지역의 사이트를 조회하려면 Microsoft가 안내하는 getAllSites API를 사용해야 하며, 이에 해당하는 cmdlet은 Get-MgAllSite입니다. 둘째, 검색 API는 createdDateTime 기준으로만 정렬할 수 있습니다.

어떤 권한이 필요할까요? Microsoft Graph PowerShell과 SharePoint 스코프

Microsoft Graph 권한은 처음 사용하는 분들이 가장 놀라워하는 부분입니다. 사이트 읽기의 경우 cmdlet 페이지에서는 가장 낮은 권한으로 Sites.Read.All을, 더 높은 권한으로 Sites.ReadWrite.All을 안내합니다. 스크립트에서 무언가를 변경해야 하는 경우가 아니라면 첫 번째 권한을 선택하십시오.

범위(scope) 이름을 일일이 기억할 필요는 없습니다. 조회를 도와주는 명령이 두 가지 있습니다.

  • Find-MgGraphCommand는 cmdlet 또는 API에 필요한 권한을 보여 줍니다. 문제 해결 페이지에서는 예시로 Find-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissions를 사용합니다.
  • Find-MgGraphPermission은 영역 또는 이름을 기준으로 권한을 찾습니다. 예를 들어 Find-MgGraphPermission application처럼 사용합니다. 출력에는 권한 유형(위임된 권한 또는 애플리케이션 권한), 관리자 동의 필요 여부, 설명이 표시됩니다.

문서에서 서로 어긋나는 부분이 하나 있으니 참고하십시오. 사이트 목록 조회에 대한 REST 페이지에는 해당 호출에 대해 애플리케이션 권한만 나와 있고, 위임된 액세스는 지원되지 않는 것으로 표시되어 있습니다. 반면 Get-MgSite의 cmdlet 페이지에는 두 가지 모두 나와 있습니다. 비프로덕션 테넌트에서 직접 호출을 테스트하고, 실패하면 오류 메시지를 자세히 읽어 보십시오. 모든 호출에 대해 cmdlet 페이지가 정확하다고 가정하지 마십시오.

무인 작업에는 앱 전용 액세스가 필요합니다. 즉, Microsoft Entra에 앱 등록을 하고, 애플리케이션 권한(API 권한이라고도 함)을 부여한 뒤 관리자 동의를 받아야 합니다. 문제 해결 페이지에서는 애플리케이션 권한에 관리자 동의가 필요하다고 설명합니다. 입력한 암호 대신 인증서 또는 관리 ID를 사용하십시오.

예: 다섯 개의 명령으로 만드는 오래된 사이트 인벤토리

이 예시의 숫자는 가상의 값입니다.

관리자가 1년 동안 아무도 변경하지 않은 사이트의 첫 번째 목록을 원한다고 가정해 보겠습니다.

  1. Connect-MgGraph -Scopes "Sites.Read.All"
  2. $sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"
  3. 이 예시에서 $sites.Count는 480을 반환합니다.
  4. $old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }
  5. $old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation

파일에 60개의 행이 있다고 가정하겠습니다. 이는 480개 중 60개, 즉 12.5%이며, 사이트 소유자와 함께 검토하기에 적당한 짧은 목록입니다. 관리자는 읽기 권한만 가지고 있으며 아무것도 변경하지 않았습니다. 사이트의 마지막 수정 날짜가 아무도 사용하지 않는다는 것을 증명하지는 않으므로, 이 목록은 삭제 목록이 아니라 질문을 시작하는 출발점으로 활용하십시오.

흔한 실수

  • 범위 없이 연결하기. 올바른 범위 없이 로그인하면 403 오류가 발생합니다. Get-MgContext를 실행하여 현재 범위가 cmdlet에 필요한 범위와 일치하는지 비교하십시오.
  • 읽기 작업에 쓰기 범위 요청하기. 보고서 작업에는 Sites.ReadWrite.All이 필요 이상입니다. Sites.Read.All부터 시작하십시오.
  • -All 빠뜨리기. 이 매개변수가 없으면 첫 페이지만 가져온 목록이 완전해 보일 수 있습니다.
  • 모듈 버전 혼동하기. Microsoft는 스크립트에 v1.0 모듈을 권장합니다. beta 모듈은 미리 보기 상태이며 예고 없이 변경될 수 있습니다.
  • 업데이트 건너뛰기. 오래된 Microsoft.Graph 버전은 버전 충돌의 알려진 원인 중 하나입니다. 다른 원인을 찾기 전에 Update-Module Microsoft.Graph를 실행하십시오.
  • 공유 컴퓨터에서 로그인 상태 유지하기. 토큰은 캐시됩니다. 작업이 끝나면 Disconnect-MgGraph를 실행하십시오.

소프트웨어가 도움이 되는 방식

대부분의 초기 요구 사항은 이미 보유한 도구로 충족할 수 있습니다. Microsoft Graph PowerShell SDK는 읽기와 내보내기를 처리합니다. SharePoint 관리 센터에서는 코드 없이 사이트 목록과 설정을 확인할 수 있습니다. Excel 또는 Power BI를 사용하면 CSV를 사이트 소유자가 읽을 수 있는 보고서로 바꿀 수 있습니다. 예약 실행의 경우 Azure Automation에서 관리 ID를 사용하여 스크립트를 실행할 수 있습니다.

격차는 첫 달이 지난 후에 살펴보십시오. 같은 인벤토리를 계속 수작업으로 다시 만들고 있다면, 출력 폴더를 고정하고 월간 알림을 설정한 저장된 스크립트로 보통 충분합니다.

다음 단계

오늘 SDK를 설치하고 Connect-MgGraph -Scopes "Sites.Read.All"를 실행한 다음 Get-MgSite -All의 출력을 CSV로 내보내십시오. 그리고 프로덕션에서 SharePoint 작업용 Microsoft Graph PowerShell을 실행하기 전에, 다음 cmdlet에 Find-MgGraphCommand를 사용해 필요한 권한을 미리 확인하십시오.

쇼 팔로우하기Spotify

Entities in this article

Microsoft Graph PowerShell Microsoft Graph SharePoint Microsoft Graph permissions

Related articles

RSS