driveItem: invite

名前空間: microsoft.graph

重要

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

driveItem の共有への招待を送信する。 共有への招待は、受信者にアクセス許可を付与し、オプションで、アイテムが共有されたことを通知する電子メールを送信します。

重要

  • アクセス許可は、ルート driveItem で作成または変更できません。ドライブの種類が personal (家庭向け OneDrive)。
  • 新しいゲストは、アプリ限定アクセスを使用して招待できません。 既存のゲストは、アプリ限定の要求で招待できます。

この 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/{drive-id}/items/{item-id}/invite
POST /groups/{group-id}/drive/items/{item-id}/invite
POST /me/drive/items/{item-id}/invite
POST /sites/{siteId}/drive/items/{itemId}/invite
POST /users/{userId}/drive/items/{itemId}/invite

要求本文

要求本文で、次のパラメーターを含む JSON オブジェクトを指定します。

{
  "requireSignIn": false,
  "sendInvitation": false,
  "roles": [ "read | write"],
  "recipients": [
    { "@odata.type": "microsoft.graph.driveRecipient" },
    { "@odata.type": "microsoft.graph.driveRecipient" }
  ],
  "message": "string"
}
パラメーター 型 説明
Recipients driveRecipient コレクション アクセス権と共有への招待を受け取る受信者のコレクション。
message String 共有の招待状に含まれるプレーンテキスト形式のメッセージ。 最大長は 2,000 文字です。
requireSignIn ブール値 共有アイテムを表示するために、招待状の受信者がサインインする必要のある場所を指定します。
sendInvitation Boolean メールまたは投稿が生成される (false) か、アクセス許可が最近作成された (true) かどうかを指定します。
roles 文字列コレクション 共有への招待の受信者に付与される役割を指定します。
expirationDateTime DateTimeOffset アクセス許可の有効期限が切れるまでの dateTime を指定します。 職場または学校用 OneDrive、および SharePoint の場合、 expirationDateTime は sharingLink アクセス許可にのみ適用されます。 職場または学校の OneDrive、SharePoint、プレミアム個人用 OneDrive アカウントで使用できます。
パスワード String 作成者が招待状に設定したパスワード。 省略可能で、家庭向け OneDrive のみです。
retainInheritedPermissions ブール値 省略可能。 true (既定) の場合、このアイテムを初めて共有するときに、共有アイテムに既存の継承されたアクセス許可が保持されます。 falseの場合、初めて共有するときに既存のアクセス許可がすべて削除されます。 SharePoint Embedded ではサポートされていません。

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文の アクセス許可 オブジェクトのコレクションを返します。

エラーが返される方法の詳細については、「 エラー応答」 を参照してください。

部分的に成功した応答

複数の受信者を招待する場合、通知が一部の受信で成功し、他の受信者で失敗する可能性があります。 この場合、サービスは 207 Multi-Status 状態コードと共に部分的な成功応答を返します。 部分的成功が返されると、失敗した各受信者の応答には、原因とその修正方法に関する情報を含む エラー オブジェクトが含まれます。 詳細については、 例 2 を参照してください。

招待の送信通知エラー

次の表に、通知の送信が失敗したときに、入れ子になった innererror オブジェクト内でアプリで発生する可能性があるその他のエラーを示します。 アプリでこれらのエラーを処理する必要はありません。

コード 説明
accountVerificationRequired 通知の送信のブロックを解除するには、アカウントの確認が必要です。
hipCheckRequired 通知送信のブロックを解除するには、HIP(ホスト侵入防止)チェックを解決する必要があります。
exchangeInvalidUser 現在のユーザーのメールボックスが見つかりませんでした。
exchangeOutOfMailboxQuota クォータ不足です。
exchangeMaxRecipients 同時に通知を送信できる受信者の最大数を超えました。

メモ: サービスは、いつでも新しいエラー コードを追加したり、古いエラー コードを返さないようにしたりできます。

例

例 1: 共有への招待を送信する

次の例は、共同作業中のファイルに関するメッセージなど、メール アドレスが robin@contoso.orgユーザーに共有への招待を送信する方法を示しています。 招待により、Robin にファイルへの読み取り/書き込みアクセス権が付与されます。

要求

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

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

{
  "recipients": [
    {
      "email": "robin@contoso.org"
    }
  ],
  "message": "Here's the file that we're collaborating on.",
  "requireSignIn": true,
  "sendInvitation": true,
  "roles": [ "write" ],
  "password": "password123",
  "expirationDateTime": "2018-07-15T14:00:00.000Z"
}

応答

次の例は応答を示しています。

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "@deprecated.GrantedTo": "GrantedTo has been deprecated. Refer to GrantedToV2",
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "grantedToV2": {
        "user": {
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20",
          "displayName": "Robin Danielsen"
        },
        "siteUser": {
          "id": "1",
          "displayName": "Robin Danielsen",
          "loginName": "Robin Danielsen"
        }
      },
      "hasPassword": true,
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

例 2:部分的に成功した共有への招待を送信する

次の例は、部分的に成功した要求を示しています。

要求

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

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

{
  "recipients": [
    {
      "email": "helga@contoso.com"
    },
    {
      "email": "robin@contoso.org"
    }
  ],
  "message": "Here's the file that we're collaborating on.",
  "requireSignIn": true,
  "sendInvitation": true,
  "roles": [ "write" ],
  "password": "password123",
  "expirationDateTime": "2018-07-15T14:00:00.000Z"
}

応答

次の例は、部分応答を示しています。

HTTP/1.1 207 Multi-Status
Content-type: application/json

{
  "value": [
    {
      "grantedTo": {
        "user": {
          "displayName": "Helga Hammeren",
          "id": "5D8CA5D0-FFF8-4A97-B0A6-8F5AEA339681"
        }
      },
      "id": "1EFG7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "helga@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "error": {
        "code":"notAllowed",
        "message":"Account verification needed to unblock sending emails.",
        "localizedMessage": "Kontobestätigung erforderlich, um das Senden von E-Mails zu entsperren.",
        "fixItUrl":"http://g.live.com/8SESkydrive/VerifyAccount",
        "innererror":{
          "code":"accountVerificationRequired"
        }
      }
    },
    {
      "grantedTo": {
        "user": {
          "displayName": "Robin Danielsen",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "robin@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

関連コンテンツ

利用可能なロールの一覧については、「 ロールのプロパティ値」を参照してください。

  • Last updated on