ノートブック、セクション、ページのコピー

  • [アーティクル]

適用対象: Office 365 のエンタープライズ ノートブックのみ

OneNote ノートブック、セクション、またはページをコピーする場合は、それぞれに対応する copy アクション エンドポイントに POST 要求を送信します。たとえば次のようにします。

POST ../notes/sections/{id}/copyToNotebook

メッセージの本文で JSON のコピー オブジェクトを送信します。要求が成功すると、OneNote API は 202 HTTP 状態コードと Operation-Location ヘッダーを返します。その後、結果について、操作エンドポイントをポーリングできます。

注意

現時点では、コピー機能は Office 365 の個人、サイト、統合グループのノートブックでサポートされていますが、OneDrive のコンシューマー ノートブックではサポートされていません。

要求 URI の構築

  1. 要求 URI を構築するには、お使いのプラットフォーム用のサービス ルート URL から開始します。

    OneDrive for Business のノートブック

    https://www.onenote.com/api/v1.0/me/notes/

    https://www.onenote.com/api/v1.0/users/{id}/notes/

    SharePoint サイトのノートブック

    https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/

    統合グループのノートブック

    https://www.onenote.com/api/v1.0/myOrganization/groups/{id}/notes/

  2. それぞれに対応する copy アクション エンドポイントを追加します。

    ページをセクションにコピーする

    ../pages/{id}/copyToSection

    セクションをノートブックにコピーする

    ../sections/{id}/copyToNotebook

    セクションをセクション グループにコピーする

    ../sections/{id}/copyToSectionGroup

    ノートブックをコピーする

    ../notebooks/{id}/copyNotebook

ノートブックは、コピー先ドキュメント ライブラリの [ノートブック] フォルダーにコピーされます。[ノートブック] フォルダーが存在しない場合は、そのフォルダーが作成されます。

完全な要求 URI は、次に示す例のいずれかのようになります。

https://www.onenote.com/api/v1.0/me/notes/sections/{id}/copyToNotebook

https://www.onenote.com/api/v1.0/users/{id}/notes/sections/{id}/copytosectiongroup

https://www.onenote.com/api/v1.0/myOrganization/siteCollections/{id}/sites/{id}/notes/pages/{id}/copyToSection

https://www.onenote.com/api/v1.0/groups/{id}/notes/notebooks/{id}/copyNotebook

注意

サービス ルート URL の詳細についてはリンク先をご覧ください。

メッセージ本文の構築

メッセージ本文では、操作に必要なパラメーターを格納する JSON オブジェクトを送信します。パラメーターが必要ない場合は、からの本文を送信してもかまいません。

パラメーター 説明
id コピー先のノートブックまたはセクション グループの ID (セクションの場合)、またはコピー先のセクションの ID (ページの場合)。

copyToNotebook、copyToSectionGroup、copyToSection でのみ使用します。
siteCollectionId アイテムのコピー先サイトを格納する SharePoint サイト コレクションの ID。

SharePoint サイトにコピーする場合にのみ、siteId と共に使用します。
siteId アイテムのコピー先 SharePoint サイトの ID。

SharePoint サイトにコピーする場合にのみ、siteCollectionId と共に使用します。
groupId アイテムのコピー先グループの ID。

統合グループにコピーする場合にのみ使用します。
renameAs コピーの名前。

copyNotebook、copyToNotebook、および copyToSectionGroup でのみ使用します。既定値は、既存のアイテムの名前になります。

ノートブック、セクション グループ、およびセクションの ID を取得する方法と、サイト コレクションおよびサイトの ID を取得する方法について学習してください。グループ ID の取得方法の詳細については、Azure AD Graph API のドキュメントを参照してください。

コピー操作のフロー例

まず、コピーするアイテムに対する copy アクションに POST 要求を送信します。コピー元とコピー先が同じテナント内にあれば、ユーザーがアクセスできる (所有しているか、共有している) ノートブックからコピーできます。

次に示す例では、SharePoint チーム サイトに個人用のノートブックをコピーします。この要求には renameAs パラメーターが含まれていないため、新しいノートブックは既存の名前を使用することになります。

POST https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923/copyNotebook
Authorization: Bearer {token}
Content-Type: application/json 

{
  "siteCollectionId":"0f6dbd5d-d179-49c6-aabd-15830ea90ca8",
  "siteId":"3ba679cf-4470-466e-bc20-053bdfec75bf"
}

注意

コピー操作では、コピー元ノートブックのアクセス許可が優先されるため、ノートブックをコピーするには、認証されたユーザーがコピー元ノートブックにアクセスできる必要があります。ただし、コピー元のアクセス許可がコピーに維持されることはありません。コピーには、そのコピーをユーザーが作成したものとしてのアクセス許可が付与されます。

呼び出しが成功すると、OneNote API は 202 状態コードと Operation-Location ヘッダーを返します。次に、応答からの抜粋を示します。

HTTP/1.1 202 Accepted
Location: https://www.onenote.com/api/v1.0/me/notes/notebooks/1-db247796-f4d1-4972-a869-942919bf9923
X-CorrelationId: 8a211d7c-220b-413d-8022-9a946499fcfb
Operation-Location: https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
...

その後で、Operation-Location エンドポイントをポーリングして、コピー操作の状態を取得します。

GET https://www.onenote.com/api/beta/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/notes/operations/copy-8a211d7c-220b-413d-8022-9a946499fcfb
Authorization: Bearer {token}
Accept: application/json

OneNote API は、現在の状態を示す OperationModel オブジェクトを返します。次に示す応答例は、状態が完了 (completed) のときに返されます。

{
  "@odata.context":"https://www.onenote.com/api/beta/$metadata#myOrganization/siteCollections('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/sites('0f6dbd5d-d179-49c6-aabd-15830ea90ca8')/notes/operations/$entity",
  "id":"copy-1c5be75c-e7db-4219-8145-a2d6c3f171a33ec9f3da-2b24-4fb1-a776-fe8c8cd1410f",
  "status":"completed",
  "createdDateTime":"2015-09-16T17:32:07.048Z",
  "lastActionDateTime":"2015-09-16T17:32:17.7777639Z",
  "resourceLocation":"https://www.onenote.com/api/v1.0/myOrganization/siteCollections/0f6dbd5d-d179-49c6-aabd-15830ea90ca8/sites/3ba679cf-4470-466e-bc20-053bdfec75bf/notes/notebooks/1-bde29eeb-66e2-4fed-8d48-51cd1bf32511",
  "resourceId":null,"
  "error":null
}

状態は、完了 (completed)、実行中 (running)、または失敗 (failed) のいずれかになります。

  • completed の場合は、resourceLocation プロパティに新しいコピーのリソース エンドポイントが格納されます。
  • running の場合は、percentComplete プロパティで完了までの見積パーセンテージが示されます。
  • failed の場合は、error プロパティと @api.diagnostics プロパティからエラー情報が得られます。

操作が完了または失敗するまで、操作エンドポイントをポーリングできます。

要求および応答に関する情報

要求データ 説明
プロトコル すべての要求は SSL/TLS HTTPS プロトコルを使用します。
承認ヘッダー Bearer {token}、{token} は、登録済みアプリの有効な OAuth 2.0 アクセス トークンになります。

これがないか、無効の場合、401 ステータス コードで要求は失敗します。「認証とアクセス許可」をご覧ください。
Content-Type ヘッダー application/json
Accept ヘッダー application/json


応答データ 説明
成功コード 202 状態の HTTP 状態コード。
Operation-Location ヘッダー 操作の状態についてポーリングする URL。

操作エンドポイントをポーリングすると、操作の状態などの情報を格納している OperationModel オブジェクトが返されます。
X-CorrelationId ヘッダー 要求を一意に識別する GUID。Microsoft サポートと問題のトラブルシューティングを行う際に、この値を Date ヘッダーの値とともに使用できます。

OneNote サービスのルート URL の構築

OneNote サービスのルート URL は、OneNote API へのすべての呼び出しで次の形式を使用します。

https://www.onenote.com/api/{version}/{location}/notes/

URL の version セグメントは、使用する OneNote API のバージョンを示しています。

  • 安定した運用コードには v1.0 を使用します。

  • 開発中の機能を試すには beta を使用します。 ベータ版の機能は変更される可能性があるため、運用コードでは使用しないでください。

URL の location セグメントは、アクセスするノートブックの場所を示しています。

  • OneDrive for Business のノートブック

    • 現在のユーザーが所有する OneNote コンテンツには me を使用します。

    • 指定されたユーザー (URL 内) が現在のユーザーと共有している OneNote コンテンツには users/{id} を使用します。 ユーザー ID を取得するには Azure AD Graph API を使用します。

  • SharePoint サイトのノートブック

    • チーム サイトとその他の SharePoint サイトには、ドキュメント ライブラリ内の OneNote ノートブックを含めることができます。

    • 現在のユーザーがログインしているテナント内のサイトの OneNote コンテンツには myOrganization/siteCollections/{id}/sites/{id} を使用します。 現在のテナントのみがサポートされており、myOrganization キーワードを使ってアクセスします。 サイト ID を取得する方法を説明します。

  • 統合グループのノートブック

    • 統合グループ (Office 365 groups とも呼ばれます) は、Office 365 Connected Experience の一部です。 グループ メンバーは、ノートブック、ファイル、メールを共有できます。

    • 現在のユーザーがメンバーになっている指定のグループの OneNote コンテンツには myOrganization/groups/{id} を使用します。 統合グループは、サポートされている唯一のグループの種類です。 グループ ID を取得するには Azure AD Graph API を使用します。

サイト コレクションとサイト ID を取得するには FromUrl メソッドを使用します

指定されたサイトの絶対 URL のサイト コレクションとサイト ID を取得するには FromUrl メソッドを使用できます。 必要な場合にのみこの呼び出しを行ってから、今後使用するために値を保存する必要があります。

サイト URL の形式は、例えば https://domain.sharepoint.com/site-a や https://domain.com/sites/site-aなど、構成に依存します。

要求の例

GET https://www.onenote.com/api/v1.0/myOrganization/siteCollections/FromUrl(url='{full-path-to-SharePoint-site}')

Authorization: Bearer {token}

Accept: application/json

応答の例

{"@odata.context":"https://www.onenote.com/api/v1.0/$metadata#Microsoft.OneNote.Api.SiteMetadata", "siteCollectionId":"09d1a587-a84b-4264-3d15-669429be8cc5", "siteId":"d9e4d5c8-683f-4363-89ae-18c4e3da91e9"}

FromUrl を使って、SharePoint サイトのノートブックを操作するための要件:

  • OneNote のノートブック、セクション グループ、セクション、ページを作成できるのは、既定のドキュメント ライブラリのサイト上のみです (一部のサイト テンプレートは、既定のドキュメント ライブラリを作成しません)。ただし、GET 要求は、サイト上のすべてのドキュメント ライブラリから OneNote コンテンツを返します。

  • OneNote サービス ルート URL は変更できません。つまり、SharePoint REST API サイト パスを使用して、そこに notes エンドポイントを追加することはできません。

  • 呼び出し元であるユーザーは、サイトのメンバーである必要があります。

  • FromUrl は、インデックス付けされたサイトでのみ機能します。 新しいサイトにインデックスを付けるには、数時間かかることがあります。

アクセス許可

OneNote のノートブック、セクション、およびページをコピーする場合は、適切なアクセス許可を要求する必要があります。アプリの動作に必要な最低限のアクセス許可を選択してください。

プラットフォーム アクセス許可の適用範囲
コンシューマー office.onenote_create, office.onenote_update_by_app, office.onenote_update
エンタープライズ Notes.Create, Notes.ReadWrite.CreatedByApp, Notes.ReadWrite, Notes.ReadWrite.All

アクセス許可のスコープと動作のしくみの詳細については、「OneNote のアクセス許可のスコープ」を参照してください。

関連項目