OneNote エンティティのアクセス許可を管理する

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

permissions エンドポイントを使用すると、ノートブック、セクション グループ、セクションに対する読み取りアクセス許可と書き込みアクセス許可を管理できます。

POST ../permissions

GET ../permissions

GET ../permissions/{permission-id}

DELETE ../permissions/{permission-id}

注意

アクセス許可の管理は 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. その後に、ターゲットのノートブック、セクション グループ、またはセクション エンティティへのパスを追加します。それに続けて、permissions エンドポイントまたは permissions/{id} エンドポイントを追加します。

完全な要求 URI は、次の例のようになります。

https://www.onenote.com/api/v1.0/me/notes/notebooks/{id}/permissions/{id}

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

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

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

注意

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

アクセス許可の作成または更新

ノートブック、セクション グループ、またはセクションのアクセス許可を作成または更新する場合は、該当するエンドポイントに POST 要求を送信します。要求ごとに作成または更新できるアクセス許可は 1 つのみです。

アクセス許可は、継承チェーンを下って、すべての OneNote のエンティティに適用されます。

より許容度の高いアクセス権を付与する場合は、アクセス許可を更新できます。ただし、アクセス権を制限するには、既存のアクセス許可を削除して、新しいアクセス許可を作成する必要があります「アクセス許可、継承、および優先順位」を参照してください。

ノートブックのアクセス許可を作成または更新する

POST ../notebooks/{notebook-id}/permissions

セクション グループのアクセス許可を作成または更新する

POST ../sectiongroups/{sectiongroup-id}/permissions

セクションのアクセス許可を作成または更新する

POST ../sections/{section-id}/permissions

メッセージ本文で、必要なパラメーターが含まれる JSON オブジェクトを送信します。

{
    "userRole": "user-role", 
    "userId": "user-login-id"
}

パラメーター	説明
userRole	アクセス許可の種類: Owner、Contributor、または Reader。
userId	アクセス許可を割り当てるユーザーまたはグループのログイン。 API は、メンバーシップ プロバイダー名 (i:0#.f|membership|username@domainname.com)、またはユーザー プリンシパル ログイン名のみ (username@domainname.com) を含むクレーム形式を受け入れます。

例

次の要求では、指定したノートブックのアクセス許可を作成します。

要求

POST ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
    "userRole": "Owner", 
    "userId": "i:0#.f|membership|alexd@domainname.com"
}

応答

HTTP/1.1 201 Created

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions/$entity",
  "userRole":"Owner",
  "userId":"i:0#.f|membership|alexd@domainname.com",
  "name":"Alex Darrow",
  "id":"1-23",
  "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
}

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

次の情報は、POST /permissions 要求に当てはまります。

要求データ	説明
プロトコル	すべての要求は SSL/TLS HTTPS プロトコルを使用します。
承認ヘッダー	Bearer {token}。{token} は、登録済みアプリの有効な OAuth 2.0 アクセス トークンになります。 これがないか、無効の場合、要求は失敗し、401 ステータス コードが表示されます。「Azure AD を使用した認証 (エンタープライズ アプリ)」をご覧ください。
アクセス許可の適用範囲	Notes.ReadWrite.CreatedByApp、Notes.ReadWrite、または Notes.ReadWrite.All

応答データ	説明
成功コード	201 HTTP ステータス コード。
応答本文	JSON 形式でのアクセス許可の OData 表現。Permission オブジェクトの説明については、「アクセス許可の取得」を参照してください。
エラー	要求が失敗すると、API は応答本文にエラーを返します。
X-CorrelationId ヘッダー	要求を一意に識別する GUID。Microsoft サポートと問題のトラブルシューティングを行う際に、この値を Date ヘッダーの値とともに使用できます。

アクセス許可の取得

ノートブック、セクション グループ、またはセクションのアクセス許可を取得する場合は、該当するエンドポイントに GET 要求を送信します。

ノートブックのアクセス許可を取得する

GET ../notebooks/{notebook-id}/permissions

ノートブックの特定のアクセス許可を取得する

GET ../notebooks/{notebook-id}/permissions/{permission-id}

セクション グループのアクセス許可を取得する

GET ../sectiongroups/{sectiongroup-id}/permissions

セクション グループの特定のアクセス許可を取得する

GET ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

セクションのアクセス許可を取得する

GET ../sections/{section-id}/permissions

セクションの特定のアクセス許可を取得する

GET ../sections/{section-id}/permissions/{permission-id}

GET 要求は、ターゲット エンティティのユーザー ロールで最高レベルのアクセス許可を返します。詳細については、「アクセス許可、継承、および優先順位」を参照してください。

GET /permissions 要求は、次に示すように OData クエリのオプションをサポートします。

GET ../permissions[?filter,orderby,select,top,skip,count]

GET ../permissions/{permission-id}[?select]

注意

permissions エンドポイントは、expand クエリ オプションをサポートしていません。

サポートされているクエリ文字列オプションや例などを含む OneNote エンティティの取得の詳細については、「OneNote コンテンツと構造を取得する」を参照してください。

Permission オブジェクト

アクセス許可には、次のプロパティが含まれます。

プロパティ	説明
名前	ユーザーまたはグループ プリンシパルの表示名。例: "name":"Everyone"
id	アクセス許可の一意識別子 (1-{principal-member-id} の形式)。例: "id":"1-4"
self	Permission オブジェクトの URL。
userId	アクセス許可の割り当て先ユーザーまたはグループのログイン。 この値は、常にクレーム形式で返されます。例： i:0#.f|membership|username@domainname.com。
userRole	アクセス許可の種類: Owner、Contributor、または Reader。

例

次の要求では、指定したノートブックのすべてのアクセス許可を取得します。

要求

GET ../v1.0/me/notes/notebooks/{notebook-id}/permissions
Authorization: Bearer {token}
Accept: application/json

応答

HTTP/1.1 200

{
  "@odata.context":"https://www.onenote.com/api/v1.0/$metadata#me/notes/notebooks('1-313dc828-dd55-4c71-82c3-f9c30a40e7c5')/permissions",
  "value":[
  {
    "userRole":"Owner",
    "userId":"c:0(.s|true",
    "name":"Everyone",
    "id":"1-4",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/1-4"
  },
  {
    "userRole":"Owner",
    "userId":"c:0-.f|rolemanager|spo-grid-all-users/8461cbdd-15a6-45c8-b177-ac24f48a8bee",
    "name":"Everyone except external users",
    "id":"1-5",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-5"
  },
  {
    "userRole":"Owner",
    "userId":"i:0#.f|membership|alexd@domainname.com",
    "name":"Alex Darrow",
    "id":"1-23",
    "self":"https://www.onenote.com/api/v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23",
  }]
}

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

次の情報は、GET /permissions 要求に当てはまります。

要求データ	説明
プロトコル	すべての要求は SSL/TLS HTTPS プロトコルを使用します。
承認ヘッダー	Bearer {token}。{token} は、登録済みアプリの有効な OAuth 2.0 アクセス トークンになります。 これがないか、無効の場合、要求は失敗し、401 ステータス コードが表示されます。「Azure AD を使用した認証 (エンタープライズ アプリ)」をご覧ください。
アクセス許可の適用範囲	Notes.Read、Notes.ReadWrite.CreatedByApp、Notes.ReadWrite、または Notes.ReadWrite.All

応答データ	説明
成功コード	200 HTTP ステータス コードおよび要求されたアクセス許可。
応答本文	JSON 形式でのアクセス許可の OData 表現。
エラー	要求が失敗すると、API は応答本文にエラーを返します。
X-CorrelationId ヘッダー	要求を一意に識別する GUID。Microsoft サポートと問題のトラブルシューティングを行う際に、この値を Date ヘッダーの値とともに使用できます。

アクセス許可の削除

ノートブック、セクション グループ、またはセクションのアクセス許可を削除する場合は、該当するエンドポイントに DELETE 要求を送信します。要求ごとに 1 つのアクセス許可を削除できます。

アクセス許可を削除すると、そのアクセス許可は継承チェーンを下って、すべての OneNote エンティティから削除されます。

ノートブックのアクセス許可を削除する

DELETE ../notebooks/{notebook-id}/permissions/{permission-id}

セクション グループのアクセス許可を削除する

DELETE ../sectiongroups/{sectiongroup-id}/permissions/{permission-id}

セクションのアクセス許可を削除する

DELETE ../sections/{section-id}/permissions/{permission-id}

例

次の要求では、指定したノートブックのアクセス許可を削除します。

DELETE ../v1.0/me/notes/notebooks/1-313dc828-dd55-4c71-82c3-f9c30a40e7c5/permissions/1-23
Authorization: Bearer {token}
Accept: application/json

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

次の情報は、DELETE /permissions 要求に当てはまります。

要求データ	説明
プロトコル	すべての要求は SSL/TLS HTTPS プロトコルを使用します。
承認ヘッダー	Bearer {token}。{token} は、登録済みアプリの有効な OAuth 2.0 アクセス トークンになります。 これがないか、無効の場合、要求は失敗し、401 ステータス コードが表示されます。「Azure AD を使用した認証 (エンタープライズ アプリ)」をご覧ください。
アクセス許可の適用範囲	Notes.ReadWrite.CreatedByApp、Notes.ReadWrite、または Notes.ReadWrite.All

応答データ	説明
成功コード	204 HTTP ステータス コード。
エラー	要求が失敗すると、API は応答本文にエラーを返します。
X-CorrelationId ヘッダー	要求を一意に識別する GUID。Microsoft サポートと問題のトラブルシューティングを行う際に、この値を Date ヘッダーの値とともに使用できます。

アクセス許可、継承、および優先順位

次に示すアクセス許可は、ノートブック、セクション グループ、およびセクションに設定できます。

アクセス許可	説明
Reader	ノートブック、セクション グループ、およびセクションに対する読み取り専用アクセス。
Contributor	ノートブック、セクション グループ、およびセクションの追加、編集、および削除が可能。
Owner	上記のすべてのアクセス許可に加え、アクセス許可の管理 (取得、作成、および削除) も可能。

OneNote エンティティのアクセス許可を管理する場合は、アクセス許可の継承と優先順位について理解している必要があります。

• 継承。エンティティは親のアクセス許可を継承します。つまり、ノートブックは、そのノートブックを含むドキュメント ライブラリのアクセス許可を継承することになります。このアクセス許可は、次に、そのノートブックに含まれる子セクション グループとセクションによって継承されます。ノートブック、セクション グループ、またはセクションにアクセス許可を明示的に設定すると、その子オブジェクトにもアクセス許可が反映されます。

• 優先順位。OneNote エンティティに競合するアクセス許可が設定されると、最高の (最も許容度の高い) アクセス権が優先されます。1 つのエンティティに明示または継承によって複数のアクセス許可が適用される場合や、ユーザーまたはグループが複数のロールに属している場合には、競合するアクセス権のレベルがユーザーやグループに付与される可能性があります。

こうした原則が、OneNote によるアクセス許可の管理方法を決定します。次に例を示します。

• ノートブックまたはセクション グループのアクセス許可を作成すると、そのアクセス許可はすべての子に適用されます。

• ノートブックまたはセクション グループのアクセス許可を削除すると、そのアクセス許可はすべての子から削除されます。

• アクセス許可を取得すると、OneNote API は競合しているアクセス許可を持つロールの最高のアクセス許可のみを返します。

• より許容度の高いアクセス権をユーザーまたはグループに付与する場合は、アクセス許可を更新できます。 ただしアクセス権を制限する場合は、まず、より許容度の高いアクセス許可を削除してから、限定的なアクセス権で新しいアクセス許可を作成する必要があります。

  これは、実際には POST /permissions 要求がエンティティのアクセス許可コレクションにユーザー ロールを追加していて、最も許容度の高いアクセス権が優先されるためです。 つまり、Reader アクセス許可は Contributor または Owner のアクセス権を含むように更新することはできますが、Contributor アクセス許可を Reader アクセス権のみが許可されるアクセス許可に更新することはできないということです。

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 の接続エクスペリエンスの一部です。 グループ メンバーは、ノートブック、ファイル、メールを共有できます。

  • 現在のユーザーがメンバーになっている指定のグループの 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 の開発
• OneNote デベロッパー センター
• OneNote の開発者ブログ
• Stack Overflow 掲載の OneNote の開発に関する質問
• OneNote GitHub のリポジトリ