共有の招待状を送信する

名前空間: microsoft.graph

重要

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

DriveItem の共有の招待状を送信します。共有の招待状は受信者にアクセス許可を提供します。また、任意で受信者に、アイテムが共有されたことを通知する電子メールを送信します。

アクセス許可

この 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 共有の招待状に含まれるプレーンテキスト形式のメッセージ。最大の長さは 2000 文字です。
requireSignIn Boolean 共有アイテムを表示するために、招待状の受信者がサインインする必要のある場所を指定します。
sendInvitation Boolean 電子メールまたは投稿が生成されるのか (false)、アクセス許可のみが作成されるのか (true) を指定します。
roles Collection(String) 共有の招待状の受信者に付与されるロールを指定します。
expirationDateTime DateTimeOffset アクセス許可の有効期限が切れる DateTime を指定します。 OneDrive for Business、SharePoint、プレミアム個人用 OneDrive アカウントで利用できます。
パスワード String 作成者が招待に設定したパスワード。 オプションと OneDrive 個人用のみ

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

HTTP 要求

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

POST /me/drive/items/{item-id}/invite
Content-type: application/json

{
  "recipients": [
    {
      "email": "ryan@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": [
    {
      "grantedTo": {
        "user": {
          "displayName": "Ryan Gregg",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "hasPassword": true,
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "ryan@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": "John Adams",
          "id": "5D8CA5D0-FFF8-4A97-B0A6-8F5AEA339681"
        }
      },
      "id": "1EFG7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "adams@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": "Ryan Gregg",
          "id": "42F177F1-22C0-4BE3-900D-4507125C5C20"
        }
      },
      "id": "CCFC7CA3-7A19-4D57-8CEF-149DB9DDFA62",
      "invitation": {
        "email": "ryan@contoso.com",
        "signInRequired": true
      },
      "roles": [ "write" ],
      "expirationDateTime": "2018-07-15T14:00:00.000Z"
    }
  ]
}

SendNotification エラー

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

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

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

備考

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

エラー応答

エラーがどのような形で返されるかについては、「エラー応答」を参照してください。