driveItem: createLink

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

driveItem driveItem を共有するためのリンクを作成します。

createLink アクションは、指定されたリンクの種類が呼び出し元アプリケーションにまだ存在しない場合、新しい共有リンクを作成します。 指定した種類の共有リンクがアプリに既に存在する場合は、既存の共有リンクが返されます。

DriveItem リソースは、そのリソースの先祖から共有アクセス許可を継承します。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類 最小特権アクセス許可 より高い特権のアクセス許可
委任 (職場または学校のアカウント) Files.ReadWrite Files.ReadWrite.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント) Files.ReadWrite Files.ReadWrite.All
アプリケーション Files.ReadWrite.All Sites.ReadWrite.All

注:

SharePoint Embedded では、コンテナーのコンテンツにアクセスするための FileStorageContainer.Selected アクセス許可が必要です。 このアクセス許可は、前述のアクセス許可とは異なります。 Microsoft Graph のアクセス許可に加えて、アプリにはこの API を呼び出すために必要な コンテナーの種類のアクセス許可 が必要です。 詳細については、「 SharePoint Embedded の認証と承認」を参照してください。

HTTP 要求

POST /drives/{driveId}/items/{itemId}/createLink
POST /groups/{groupId}/drive/items/{itemId}/createLink
POST /me/drive/items/{itemId}/createLink
POST /sites/{siteId}/drive/items/{itemId}/createLink
POST /users/{userId}/drive/items/{itemId}/createLink

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
Content-Type application/json. 必須です。

要求本文

要求本文はアプリケーションが要求する共有リンクのプロパティを定義します。 要求は、次のプロパティを含む JSON オブジェクトである必要があります。

プロパティ 型 説明
type String 省略可能。 作成する共有リンクの種類。
scope String 省略可能。 作成するリンクのスコープ。 anonymous、organization、またはusers
expirationDateTime DateTimeOffset 省略可能。 DateTime の yyyy-MM-ddTHH:mm:ssZ 形式の文字列は、アクセス許可の有効期限を示します。
パスワード String 省略可能。 作成者が共有リンクのパスワードを設定します。
Recipients driveRecipient コレクション 省略可能。 共有リンクへのアクセスを受け取る受信者のコレクション。
retainInheritedPermissions ブール値 省略可能。 true (既定) の場合、このアイテムを初めて共有するときに、共有アイテムに既存の継承されたアクセス許可が保持されます。 falseの場合、初めて共有するときに既存のアクセス許可がすべて削除されます。 SharePoint Embedded ではサポートされていません。
sendNotification ブール型 true場合、このメソッドは、メールで共有リンクをrecipientsで指定されたユーザーに送信します。 OneDrive for Business または SharePoint に適用されます。 既定値は false です。 省略可能。

type パラメーターには次の値を使用できます。

種類の値 説明
view driveItem への読み取り専用リンクを作成します。
レビュー driveItem へのレビュー リンクを作成します。 このオプションは、OneDrive for Business と SharePoint のファイルでのみ使用できます。
edit driveItem への読み取り/書き込みリンクを作成します。
埋め込み driveItem への埋め込み可能なリンクを作成します。
blocksDownload driveItem へのダウンロードをブロックする読み取り専用リンクを作成します。 このオプションは、OneDrive for Business と SharePoint のファイルでのみ使用できます。
createOnly driveItem へのアップロード専用リンクを作成します。 このオプションは、OneDrive for Business と SharePoint のフォルダーでのみ使用できます。
addressBar 新しく作成されたファイルのブラウザー アドレス バーに表示される既定のリンクを作成します。 OneDrive for Business および SharePoint の場合のみ使用できます。 organization管理者は、このリンクタイプがサポートするかどうかを構成し、サポートする機能を指定します。
adminDefault organization の管理者によって決定された driveItem への既定のリンクを作成します。 OneDrive for Business および SharePoint の場合のみ使用できます。 管理者は、organization のポリシーを適用します。

スコープの種類

scope パラメーターには次の値を使用できます。

値 説明
匿名 リンクを知っているすべてのユーザーは、サインインするこなくアクセスできます。 これには、organization 外のユーザーも含まれる場合があります。 管理者は匿名リンクのサポートを無効にすることができます。
組織 組織 (テナント) にサインインしているユーザーは、リンクを使用してアクセスできます。 OneDrive for Business および SharePoint の場合のみ使用できます。
users 受信者のコレクション内の特定のユーザーは、リンクを使用してアクセスできます。 OneDrive for Business および SharePoint の場合のみ使用できます。

応答

正常に実行されると、このメソッドは要求された共有アクセス許可を表す応答本文で、単一のアクセス許可リソースを返します。

driveItem に新しい共有リンクが作成された場合は応答が201 Createdされ、既存のリンクが返された場合は200 OK応答が返されます。

例

次の例では、ユーザーの OneDrive の {itemId} で指定された driveItem に対して共有リンクを作成するように要求します。 共有リンクは、読み取り専用でそのリンクによってだれでも使用可能になるよう構成されます。 OneDrive for Business ユーザーと SharePoint ユーザーの場合は、sendNotification パラメーターを使用して共有リンクを作成します。 共有リンクは、メールで受信者に送信されます。 retainInheritedPermissions が false の場合、初めて共有するときに既存のアクセス許可がすべて削除されます。

要求

POST https://graph.microsoft.com/beta/me/drive/items/{itemId}/createLink
Content-Type: application/json

{
  "type": "view",
  "scope": "anonymous",
  "password": "String",
  "recipients": [
    {
      "@odata.type": "microsoft.graph.driveRecipient"
    }
  ],
  "sendNotification": true,
  "retainInheritedPermissions": false
}

応答

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "view",
    "scope": "anonymous",
    "webUrl": "https://1drv.ms/A6913278E564460AA616C71B28AD6EB6",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  },
  "hasPassword": true
}

OneDrive for Business および SharePoint は、会社の共有可能リンクをサポートしています。 これらは匿名リンクに似ていますが、所有している organization のメンバーに対してのみ機能する点が異なります。 会社の共有可能リンクを作成するには、scope パラメーターで値 organization を指定して使用します。

要求

POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "edit",
  "scope": "organization"
}

応答

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["write"],
  "link": {
    "type": "edit",
    "scope": "organization",
    "webUrl": "https://contoso-my.sharepoint.com/personal/ellen_contoso_com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

リンクの種類で embed を使用する場合、返される webUrl は <iframe> HTML 要素に埋め込むことができます。 埋め込みリンクが作成されると、 webHtml プロパティにはコンテンツをホストする <iframe> の HTML コードが含まれます。

注: 埋め込みリンクは、OneDrive 個人用でのみサポートされます。

要求

次の例は要求を示しています。

POST https://graph.microsoft.com/beta/me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

応答

次の例は要求を示しています。

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "123ABC",
  "roles": ["read"],
  "link": {
    "type": "embed",
    "webHtml": "<IFRAME src=\"https://onedrive.live.com/...\"></IFRAME>",
    "webUrl": "https://onedive.live.com/...",
    "application": {
      "id": "1234",
      "displayName": "Sample Application"
    },
  }
}

注釈

  • organization の既定のポリシーと driveItem に対する呼び出し元のアクセス許可に基づいてリンクを作成するには、scope パラメーターと type パラメーターを省略します。
  • このアクションを使用して作成されたリンクは、既定の有効期限ポリシーが organization に適用されていない限り、有効期限が切れません。
  • リンクは driveItem の共有アクセス許可に表示され、 driveItem の所有者が削除できます。
  • driveItem がチェックアウトされていない限り、リンクは常に driveItem の現在のバージョンを指します (SharePoint のみ)。