DriveItem の共有リンクを作成するCreate a sharing link for a DriveItem

重要

Microsoft Graph の/betaバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでは、これらの API の使用はサポートされていません。Use of these APIs in production applications is not supported.

createLink アクションを使用して、共有リンクを使って DriveItem を共有できます。You can use createLink action to share a DriveItem via a sharing link.

createLink アクションは、呼び出し元のアプリケーションに指定されたリンクの種類が存在しない場合に、新しい共有リンクを作成します。指定された種類の共有リンクがアプリで既に存在している場合、既存の共有リンクが返されます。The createLink action will create a new sharing link if the specified link type doesn't already exist for the calling application. If a sharing link of the specified type already exists for the app, the existing sharing link will be returned.

DriveItem リソースは、そのリソースの先祖から共有アクセス許可を継承します。DriveItem resources inherit sharing permissions from their ancestors.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) Files.ReadWrite、Files.ReadWrite.All、Sites.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All, Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) Files.ReadWrite、Files.ReadWrite.AllFiles.ReadWrite, Files.ReadWrite.All
アプリケーションApplication Files.ReadWrite.All、Sites.ReadWrite.AllFiles.ReadWrite.All, Sites.ReadWrite.All

HTTP 要求HTTP request

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

要求本文Request body

要求本文はアプリケーションが要求する共有リンクのプロパティを定義します。The body of the request defines properties of the sharing link your application is requesting. 要求は、次のプロパティを含む JSON オブジェクトである必要があります。The request should be a JSON object with the following properties.

プロパティProperty Type 説明Description
typetype stringstring 作成する共有リンクの種類。The type of sharing link to create. 表示、編集、または埋め込みのいずれかです。Either view, edit, or embed.
passwordpassword stringstring 作成者によって設定された共有リンクのパスワード。The password of the sharing link that is set by the creator. 省略可能および OneDrive 個人用のみ。Optional and OneDrive Personal only.
expirationDateTimeexpirationDateTime stringstring Yyyy-mm-ddthh: mm: ssZ DateTime の形式の文字列は、アクセス許可の有効期限を示します。A String with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission.
scopescope stringstring 省略可能。Optional. 作成するリンクのスコープ。The scope of link to create. 匿名または組織のどちらかです。Either anonymous or organization.

type パラメーターには次の値を使用できます。The following values are allowed for the type parameter.

種類の値Type value 説明Description
ビューview その DriveItem への読み取り専用リンクを作成します。Creates a read-only link to the DriveItem.
editedit その DriveItem への読み取り/書き込みリンクを作成します。Creates a read-write link to the DriveItem.
埋め込みembed その DriveItem への埋め込み可能なリンクを作成します。Creates an embeddable link to the DriveItem. このオプションは OneDrive 個人用のファイルでのみ選択可能です。This option is only available for files in OneDrive personal.

スコープの種類Scope types

scope パラメーターには次の値を使用できます。The following values are allowed for the scope parameter. scope パラメーターが指定されていない場合、組織の既定のリンクの種類が作成されます。If the scope parameter is not specified, the default link type for the organization is created.

Value 説明Description
匿名anonymous リンクを持つすべてのユーザーが、サインインを必要とせずにアクセスできます。Anyone with the link has access, without needing to sign in. これには、組織外のユーザーが含まれることがあります。This may include people outside of your organization. 匿名リンクのサポートは、管理者によって無効にされている場合があります。Anonymous link support may be disabled by an administrator.
組織organization 組織 (テナント) にサインインしているユーザーは、リンクを使用してアクセス権を取得することができます。Anyone signed into your organization (tenant) can use the link to get access. OneDrive for business と SharePoint でのみ使用できます。Only available in OneDrive for Business and SharePoint.

応答Response

正常に実行されると、このメソッドは要求された共有アクセス許可を表す応答本文で、単一のアクセス許可リソースを返します。If successful, this method returns a single Permission resource in the response body that represents the requested sharing permissions.

応答は、アイテムに新しい共有リンクが作成される場合は 201 Created、既存のリンクが返される場合は 200 OK となります。The response will be 201 Created if a new sharing link is created for the item or 200 OK if an existing link is returned.

Example

次の例では、ユーザーの OneDrive の {itemId} で指定された DriveItem に対して共有リンクを作成することを要求します。The following example requests a sharing link to be created for the DriveItem specified by {itemId} in the user's OneDrive. 共有リンクは、読み取り専用でそのリンクによってだれでも使用可能になるよう構成されます。The sharing link is configured to be read-only and usable by anyone with the link.

要求Request

POST /me/drive/items/{itemId}/createLink
Content-type: application/json

{
  "type": "view",
  "password": "ThisIsMyPrivatePassword",
  "scope": "anonymous"
}

応答Response

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 は、会社の共有可能リンクをサポートしています。OneDrive for Business and SharePoint support company sharable links. これらは匿名リンクに似ていますが、所有組織のメンバーだけが使用できる点が異なります。These are similar to anonymous links, except they only work for members of the owning organization. 会社の共有可能リンクを作成するには、scope パラメーターで値 organization を指定して使用します。To create a company sharable link, use the scope parameter with a value of organization.

要求Request

POST /me/drive/items/{item-id}/createLink
Content-Type: application/json

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

応答Response

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 コードが含まれます。When using the embed link type, the webUrl returned can be embedded in an <iframe> HTML element. When an embed link is created the webHtml property contains the HTML code for an <iframe> to host the content.

注: 埋め込みリンクは、OneDrive 個人用でのみサポートされます。Note: Embed links are only supported for OneDrive personal.

要求Request

POST /me/drive/items/{item-id}/createLink
Content-Type: application/json

{
  "type": "embed"
}

応答Response

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"
    },
  }
}

注釈Remarks

  • 組織に既定の有効期限ポリシーが適用されている場合を除き、このアクションを使用して作成されたリンクに期限はありません。Links created using this action do not expire unless a default expiration policy is enforced for the organization.
  • リンクはそのアイテムの共有アクセス許可に表示され、アイテムの所有者はそれを削除できます。Links are visible in the sharing permissions for the item and can be removed by an owner of the item.
  • リンクは、そのアイテムがチェックアウトされない限り、常にアイテムの現在のバージョンをポイントします (SharePoint の場合のみ)。Links always point to the current version of a item unless the item is checked out (SharePoint only).