共有の招待状を送信する

  • [アーティクル]

名前空間: microsoft.graph

重要

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

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

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 Collection(driveRecipient) アクセス権と共有の招待を受け取る受信者のコレクション。
message String 共有の招待状に含まれるプレーンテキスト形式のメッセージ。 最大長 2,000 文字。
requireSignIn ブール値 共有アイテムを表示するために、招待状の受信者がサインインする必要のある場所を指定します。
sendInvitation Boolean 電子メールまたは投稿が生成されるか (false) か、アクセス許可が最近作成された (true) かどうかを指定します。
roles Collection(String) 共有招待の受信者に付与されるロールを指定します。
expirationDateTime DateTimeOffset アクセス許可の有効期限が切れる dateTime を指定します。 OneDrive for Businessと SharePoint の場合、xpirationDateTime は sharingLink アクセス許可にのみ適用されます。 OneDrive for Business、SharePoint、Premium 個人用 OneDrive アカウントで使用できます。
パスワード String 作成者による招待に設定されたパスワード。 オプションと OneDrive Personal のみ
retainInheritedPermissions ブール値 省略可能。 (既定値) の場合 true 、このアイテムを初めて共有するときに、既存の継承されたアクセス許可が共有アイテムに保持されます。 の場合 false、共有時に既存のすべてのアクセス許可が初めて削除されます。

例

次の使用例は、共同作業中のファイルに関するメッセージを含むメール アドレス "ryan@contoso.org" を持つユーザーに共有の招待を送信します。 この招待により、Ryan にはファイルへの読み取り/書き込みアクセス権が付与されます。

HTTP 要求

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

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

部分的な成功応答

複数の受信者を招待する場合、通知が一部の受信者に対して成功し、他の受信者に対して失敗する可能性があります。 この場合、サービスは HTTP 状態コード 207 で部分的な成功応答を返します。 部分的な成功が返されると、失敗した各受信者の応答には、問題の原因とその修正方法に関する情報を含むオブジェクトが含まれます error 。

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

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

SendNotification エラー

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

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

メモ： サービスは、新しいエラー コードを追加したり、古いエラー コードをいつでも返したりすることができます。

注釈

  • driveType が (OneDrive personal) のpersonalドライブでは、ルート DriveItem に対するアクセス許可を作成または変更できません。
  • 使用可能なロールの一覧については、「 roles プロパティの値」を参照してください。

エラー応答

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