この記事について
この記事は、生成AIを活用した自動生成フローで作成しています。PnP PowerShell と Microsoft Graph の公式情報を確認し、2026年9月時点の認証方法・ファイル操作・大規模ライブラリの注意点に合わせて整理しています。検証ステータス：📘 公式情報確認済み・SharePoint実機未確認
SharePoint Online のファイルを PowerShell で扱うなら、現在は旧 SharePointPnPPowerShellOnline ではなく PnP.PowerShell を使うのが基本です。最初から一括処理へ進まず、まず読み取りだけで接続を確認し、その後にテストファイル1個で「アップロード → SharePoint側で確認 → ダウンロード」まで動かすと、権限やパスの問題を切り分けやすくなります。
この記事では PnP PowerShell を中心に、最後に Microsoft Graph PowerShell SDK を選ぶ場面も整理します。
まず試す：読み取りだけで接続できるか確認する
PnP PowerShell の現行インストールガイドでは PowerShell 7.4.0 以上が必要です。まず自分の環境を確認します。
$PSVersionTable.PSVersion
Get-Module PnP.PowerShell -ListAvailable |
Sort-Object Version -Descending |
Select-Object -First 1 Name, Version, PathPnP PowerShell が未導入なら、ユーザー単位でインストールできます。
Install-Module PnP.PowerShell -Scope CurrentUser現在の PnP PowerShell では、自分のテナント用 Entra ID アプリ登録と Client ID を使う構成が基本です。2024年9月に従来の共有 PnP Management Shell アプリが削除されたため、古い記事の認証例はそのまま使えない場合があります。
$SiteUrl = "https://contoso.sharepoint.com/sites/Project"
$ClientId = "00000000-0000-0000-0000-000000000000"
Connect-PnPOnline -Url $SiteUrl -Interactive -ClientId $ClientId接続後は、いきなり書き込まずにファイル一覧を取得します。
Get-PnPFolderItem `
-FolderSiteRelativeUrl "Shared Documents" `
-ItemType File |
Select-Object -First 10 Name, ServerRelativeUrlここを見る：ファイル名と ServerRelativeUrl が取得できれば、少なくとも認証・サイトURL・読み取り権限・ライブラリ指定の確認が進みます。ここで失敗するなら、アップロード処理を追加する前に接続条件を直した方が切り分けやすくなります。
テストファイル1個をアップロードする
読み取りができたら、業務ファイルではなく時刻入りのテストファイルを1個だけ作ります。同じ名前を使い回さないので、既存ファイルを意図せず触るリスクを下げられます。
$TargetFolder = "Shared Documents/AutomationTest"
$Stamp = Get-Date -Format "yyyyMMdd-HHmmss"
$LocalFile = Join-Path $env:TEMP "pnp-upload-$Stamp.txt"
"PnP PowerShell upload test: $(Get-Date -Format o)" |
Set-Content -Path $LocalFile -Encoding utf8
Get-Item $LocalFile |
Select-Object FullName, Length, LastWriteTime内容とファイル名を確認してからアップロードします。
Add-PnPFile -Path $LocalFile -Folder $TargetFolderAdd-PnPFile の現行構文には -Overwrite パラメータはありません。Web上の古いサンプルに付いている場合は、そのままコピーせず Get-Command Add-PnPFile -Syntax や公式ドキュメントで現在の構文を確認してください。
SharePoint側に本当に作成されたか確認する
「コマンドがエラーにならなかった」だけで成功扱いにはしません。アップロードしたファイルを SharePoint 側から取り直して確認します。
$UploadedName = Split-Path $LocalFile -Leaf
$RemoteUrl = "/sites/Project/Shared Documents/AutomationTest/$UploadedName"
$RemoteFile = Get-PnPFile -Url $RemoteUrl -AsFileObject
$RemoteFile |
Select-Object Name, Length, TimeLastModified, ServerRelativeUrlここを見る：ファイル名・サイズ・更新日時・URL が想定どおりかを確認します。定期処理にするときも「送信処理」と「結果確認」を分けておくと、送ったつもりの状態を減らせます。
ダウンロードして内容まで確かめる
PnP PowerShell でファイルを取得するコマンドは Get-PnPFile です。古い記事にある Download-PnPFile を探す必要はありません。
$DownloadDir = Join-Path $env:TEMP "SharePointDownload"
New-Item -ItemType Directory -Path $DownloadDir -Force | Out-Null
Get-PnPFile `
-Url $RemoteUrl `
-Path $DownloadDir `
-FileName $UploadedName `
-AsFile `
-Force
$DownloadedFile = Join-Path $DownloadDir $UploadedName
Get-Item $DownloadedFile |
Select-Object FullName, Length, LastWriteTime今回のテストファイルについて内容まで同じか確かめたい場合は、アップロード前とダウンロード後のハッシュを比較します。
Get-FileHash $LocalFile
Get-FileHash $DownloadedFile同じアルゴリズムで SHA256 が一致すれば、このテストでは「ローカルで作成した内容」と「SharePointから取り直した内容」が一致したことを確認できます。
なぜ古いサンプルはそのまま動かないのか
SharePoint の PowerShell 記事は長く検索結果に残るため、現在の PnP PowerShell と前提が違うコードが混ざりやすい分野です。特に次の4点は確認しておくと切り分けが早くなります。
| 古い前提・症状 | 現在確認すること |
|---|---|
SharePointPnPPowerShellOnline を使っている |
現行の PnP.PowerShell への移行を確認する |
Connect-PnPOnline -Interactive だけで接続している |
自テナント用の Entra ID アプリ登録と Client ID を確認する |
Download-PnPFile が出てくる |
ファイル取得は Get-PnPFile の現行構文を確認する |
Add-PnPFile -Overwrite が出てくる |
現行の Add-PnPFile 構文を確認し、テスト時は一意なファイル名を使う |
検索で見つけたコードをそのまま信用せず、手元のモジュールで構文を確認するのも有効です。
Get-Command Connect-PnPOnline -Syntax
Get-Command Add-PnPFile -Syntax
Get-Command Get-PnPFile -Syntax
Get-Command Get-PnPFolderItem -Syntax仕事で使うなら、1ファイル確認から段階的に広げる
1ファイルの往復確認ができたら、初めて一括処理へ広げます。業務で重要なのは「大量に動くこと」より、どこまで処理できたかを後から確認できることです。
フォルダ内のファイルをまとめて取得する
$Folder = "Shared Documents/Reports"
$DownloadDir = "C:\Work\SharePointBackup"
New-Item -ItemType Directory -Path $DownloadDir -Force | Out-Null
$Files = Get-PnPFolderItem `
-FolderSiteRelativeUrl $Folder `
-ItemType File
foreach ($File in $Files) {
Write-Host "Downloading: $($File.ServerRelativeUrl)"
Get-PnPFile `
-Url $File.ServerRelativeUrl `
-Path $DownloadDir `
-FileName $File.Name `
-AsFile `
-Force
}サブフォルダまで再帰すると SharePoint への呼び出し回数が増えます。また、PnP PowerShell の現行ドキュメントでは、5,000件を超えるドキュメントライブラリを扱う場合は Get-PnPFolderItem の -List パラメータを使う必要があると案内されています。最初から全件再帰にせず、対象範囲を絞って確認してください。
無人実行は対話ログインと分ける
タスクスケジューラやサーバーで定期実行する場合、-Interactive は向きません。PnP PowerShell は証明書、Managed Identity、Federated Identity などの認証方法を提供しています。ユーザー名・パスワードをスクリプトへ直書きするのではなく、実行環境に合う非対話方式を選びます。
証明書ストアを使う構成例は次の形です。
$SiteUrl = "https://contoso.sharepoint.com/sites/Project"
$ClientId = "00000000-0000-0000-0000-000000000000"
$Tenant = "contoso.onmicrosoft.com"
$Thumbprint = "0123456789ABCDEF0123456789ABCDEF01234567"
Connect-PnPOnline `
-Url $SiteUrl `
-ClientId $ClientId `
-Tenant $Tenant `
-Thumbprint $Thumbprint本番運用では、対象サイトと処理内容に必要な権限だけを付与し、処理件数・失敗ファイル・再試行結果をログに残す設計にすると運用しやすくなります。
PnP PowerShell と Microsoft Graph はどう選ぶか
PnP PowerShell は SharePoint 固有の操作を PowerShell から扱いやすい一方、オープンソースのコミュニティ提供モジュールで、Microsoft の直接サポートや SLA はありません。組織として Microsoft 公式 SDK を標準にしたい場合は Microsoft Graph PowerShell SDK も選択肢です。
| 観点 | PnP PowerShell | Microsoft Graph PowerShell SDK |
|---|---|---|
| SharePoint固有操作 | cmdlet が豊富で扱いやすい | Graph の site / drive / driveItem を理解して使う |
| ファイル取得 | Get-PnPFile |
Get-MgDriveItemContent |
| ファイル内容の更新 | Add-PnPFile など |
Set-MgDriveItemContent など |
| サポートモデル | コミュニティ提供。Microsoftの直接SLAなし | Microsoft Graph の公式 SDK |
「SharePoint の日常運用を PowerShell で組み立てたい」なら PnP PowerShell は実用的です。一方、他の Microsoft 365 API と統一したい、組織標準として公式 SDK を優先したい場合は Graph を検討します。
つまずいたときは、書き込み前の段階へ戻る
| 症状 | 確認すること |
|---|---|
| Client ID を要求される | 自テナント用 Entra ID アプリ登録と -ClientId を確認する |
| Access denied / 403 | ユーザーまたはアプリの権限、対象サイト、対象ライブラリを確認する |
| ファイルが見つからない | site-relative / server-relative URL、ライブラリ名、空白、サブフォルダを確認する |
| 大量処理が遅い | 全件再帰を避け、対象を絞る。大規模ライブラリでは -List も確認する |
接続確認 → 1ファイル → 結果確認という順番を崩さなければ、「認証の問題」「パスの問題」「書き込みの問題」「大量処理の問題」を分けて調べやすくなります。
まとめ
- SharePoint Online を PowerShell で扱うなら、旧モジュールではなく現行の
PnP.PowerShellと現在の認証方式を確認する。 - 読み取り確認のあと、テストファイル1個でアップロード・再取得・ダウンロードまで確かめる。
- 一括処理や無人実行は、1ファイルの往復が確認できてから対象範囲・権限・ログを設計する。
- Microsoft の直接サポートや公式 SDK を重視する組織では Microsoft Graph PowerShell SDK も比較する。
公式情報・一次情報
- PnP PowerShell — 現行情報・認証変更・サポートモデル
- Installing PnP PowerShell — 必要な PowerShell バージョン
- PnP PowerShell Authentication — 対話実行・無人実行の認証方式
- Connect-PnPOnline — 接続方法
- Add-PnPFile — ファイルのアップロード
- Get-PnPFile — ファイルの取得・ダウンロード
- Get-PnPFolderItem — フォルダ内のファイル一覧・大規模ライブラリの注意点
- Get-MgDriveItemContent — Microsoft Graph PowerShell SDK でのファイル取得
- Set-MgDriveItemContent — Microsoft Graph PowerShell SDK でのファイル内容更新
この記事の更新履歴
この記事は、生成AIを活用した自動レビュー・更新フローにより内容を見直し、必要な修正を反映しています。
2026年9月12日
- 変更 現行の
PnP.PowerShellと Entra ID アプリ登録を前提に、認証とファイル操作の説明を更新しました。 - 変更 読者が上から順に「読み取り確認 → 1ファイルのアップロード → 結果確認 → ダウンロード → 実務化」へ進める構成に組み直しました。
- 追加 Microsoft Graph PowerShell SDK との使い分け、大規模ライブラリ、無人実行時の注意点を整理しました。
