ファイル・アップロード
/documents/api/1.2/files/data
アップロード先とファイル情報を指定するマルチパート・リクエストを使用して、新しいファイルをアップロードします。
ノート:
ファイル名は大文字/小文字が区別されません。すなわち、File_Name
とfile_name
は同じであるとみなされます。 特定のフォルダ内で、2つのファイルに同じ名前を指定することはできません。
デフォルトでは、同じ名前のファイルがターゲット宛先に存在する場合、アップロードされたファイルが新規リビジョンとして既存のファイルを置き換えます。
リクエストはマルチパートのHTTPリクエストであり、一方のパートがparentID
ありのJSONオブジェクト(jsonInputParameters
)で、もう一方のパートがファイル自体の内容(primaryFile
)です。 別のJSONオブジェクト(metadataValues
)を使用してメタデータ値を設定することもできます。
リクエスト
- multipart/form-data
- accessToken(optional): string
現在のユーザーに親フォルダへのアクセスを許可するApplinkアクセス・トークン。 このパラメータは、
appLinkID
が使用されている場合は必須です。 これはaccessTokenまたはAccessTokenとして使用できます。 - appLinkID(optional): string
現在のユーザーに親フォルダへのアクセスを許可するApplink ID。 パラメータ
appLinkID
が使用されるときはいつでも、パラメータaccessToken
も提供されなければなりません。 働くには、このapplinkは、少なくともコントリビュータ・ロールが付与されていなければなりません。 appLinkIDまたはAppLinkIDとして使用できます。 - dAccessCode(optional): string
保護されたパブリック・リンクを使用するために必要なアクセス・コード。 次の形式のCookieヘッダーの一部として送信する必要があります:
dAccessCode-<linkID>=<passcodeValue>
- linkID(optional): string
現在のユーザーにこのファイルへのアクセスを許可する、パブリック・リンクのパブリック・リンクID。 機能させるには、このパブリック・リンクにコントリビュータ・ロールが付与されている必要があります。 linkIDまたはLinkIDとして使用できます。
- jsonInputParameters: string
このパラメータを使用して、
parentID
パラメータとduplicateResolution
パラメータをJSONペイロードとしてリクエストに含めることができます。 このパラメータは、primaryFile
パラメータの前にする必要があります。parentID
を、ファイルをアップロードするフォルダのグローバル一意識別子(GUID)に設定します。
たとえば:parentID
パラメータは、このJSONペイロードの一部として送信する必要があります。 このパラメータは必須です。{
"parentID": "FB4CD874EF94CD2CC1B60B72T"
}また、重複するファイル名との競合を解決するために、
duplicateResolution
をTimeStampSuffix
に設定できます。
たとえば:duplicateResolution
パラメータは、このJSONペイロードの一部として送信できます。 このパラメータは省略可能です。{
"parentID": "FB4CD874EF94CD2CC1B60B72T",
"duplicateResolution": "TimeStampSuffix"
} - metadataValues(optional): string
このパラメータを使用して、メタデータ値を、すでに親フォルダに割り当てられているコレクションに設定できます。 ルールは、設定メタデータ値REST APIに適用されるルールと同じです。
Content-Type: application/json
を使用して、この情報をJSONオブジェクトとして示します。たとえば:
{
"collection": "CollectionA",
"fieldA": "valueA",
"fieldB": "valueB",
"fieldC": "valueC"
} - primaryFile: file
アップロードするファイル。 これは、
jsonInputParameters
パラメータの後にする必要があります。
レスポンス
- application/json
- application/xml
201レスポンス
- Location: string
新規作成されたリソースのURIは、
Locationヘッダー
フィールドにあります。
object
- errorCode(optional): number
エラー・コードがゼロ(0)の場合は、エラーなしです
- errorMessage(optional): string
エラー・コードがゼロ(0)の場合は、エラーなしです
- object FileDefinition
ファイル情報
object
- createdBy(optional): object User
ユーザー情報
- createdTime(optional): string
ファイルの作成日。
- id(optional): string
ファイルのグローバル一意識別子(GUID)。
- mimeType(optional): string
ファイルのファイル形式
- modifiedBy(optional): object User
ユーザー情報
- modifiedTime(optional): string
ファイルの最終更新日
- name(optional): string
ファイル名。
- ownedBy(optional): object User
ユーザー情報
- parentID(optional): string
親フォルダのグローバル一意識別子(GUID)。 親フォルダがユーザーのホーム・フォルダの場合、
parentID
の値はself
です。 - reservationTime(optional): string
ファイルが予約された時刻(ファイルが予約されていない場合、レスポンス・データから除外されます)
- reservedBy(optional): object User
ユーザー情報
- size(optional): string
ファイルのサイズ(バイト単位)。
- type(optional): string
アイテム・タイプ
file
。 - version(optional): string
ファイルのバージョン。
object
- displayName(optional): string
ユーザーの表示名
- id(optional): string
ユーザーのグローバル一意識別子(GUID)。
- loginName(optional): string
ユーザーのログイン名。
- type(optional): string
アイテム・タイプ
user
。
{
"id":"DB1C5AF480FFE61C588027A8T0000000000100000001",
"parentID":"FF4729683CD68C1AFB1AE87DT0000000000100000001",
"name":"example.txt",
"type":"file",
"size":"13",
"version":"1",
"createdTime":"2014-02-21T21:32:37Z",
"modifiedTime":"2014-02-21T21:32:37Z",
"createdBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"ownedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"modifiedBy":{
"displayName":"User AA",
"id":"U0EAA20910FAF3052ACB79E4T00000000001",
"loginName":"userAALoginName",
"type":"user"
},
"errorCode":"0",
"errorMessage":"Successfully checked in content item 'ADC412030000000000000000000002'."
}
400レスポンス
403レスポンス
404レスポンス
例
次の例では、マルチパート・リクエストを使用して新しいファイルをアップロードします。
POST .../files/data
リクエスト・ヘッダー
このリクエストは、次の一般形式の境界デリミタを指定したマルチパート・リクエストです。
Content-Type: multipart/form-data; boundary=---1234567890
リクエスト本文
-----1234567890 Content-Disposition: form-data; name="parameters" Content-Type: application/json { "parentID":"FB4CD874EF94CD2CC1B60B72T0000000000100000001" } -----1234567890 Content-Disposition: form-data; name="primaryFile"; filename="example.txt" Content-Type: text/plain <File Content> -----1234567890--
代替リクエスト本文の例を次に示します。
-----1234567890 Content-Disposition: form-data; name="jsonInputParameters" { "parentID":"FB4CD874EF94CD2CC1B60B72T0000000000100000001" } -----1234567890 Content-Disposition: form-data; name="primaryFile"; filename="example.txt" Content-Type: text/plain <File Content> -----1234567890--
HTTPステータス・コード
HTTP_STATUS = 200
JSONレスポンス
{ "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "createdTime": "2014-02-21T21:11:24Z", "errorCode": "0", "errorMessage": "Successfully checked in content item 'ADC412030000000000000000000002'.", "id": "D34A657B8723A96097F80926T0000000000100000001", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "modifiedTime": "2014-02-21T21:11:24Z", "name": "example.txt", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "U0EAA20910FAF3052ACB79E4T00000000001", "type": "user" }, "parentID": "FB4CD874EF94CD2CC1B60B72T0000000000100000001", "size": "13", "type": "file", "version": "1" }
例2
次の例では、マルチパート・リクエストを使用して新しいファイルをアップロードします。 このファイルは現在のユーザーに所有または共有されていないフォルダ構造にあるため、この例では、パブリック・リンクIDを使用します。
POST .../files/data
リクエスト・ヘッダー
Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
リクエスト本文
-----------------------------7dc7c172076a Content-Disposition: form-data; name="parameters" Content-Type: application/json { "parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518" } -----------------------------7dc7c172076a Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt" Content-Type: text/plain This is idcTestNewFileREST.txt v1 -----------------------------7dc7c172076a--
HTTPステータス・コード
HTTP_STATUS = 201
JSONレスポンス
{ "createdBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "createdTime": "2016-06-30T20:09:54Z", "errorCode": "0", "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000000801", "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000000801'.", "id": "D34BA589F6ACC07B6EA371C7B5D17B95F47087F4E518", "mimeType": "text/plain", "modifiedBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "modifiedTime": "2016-06-30T20:09:54Z", "name": "idcTestNewFileREST.txt", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518", "size": "33", "type": "file", "version": "1" }
例3
次の例では、マルチパート・リクエストを使用して新しいファイルをアップロードします。 このファイルは現在のユーザーに所有または共有されていないフォルダ構造にあるため、この例では、アクセス・コードで保護されているパブリック・リンクIDを使用します。 アクセス・コード( test12345
)は、Cookieの一部としてリクエスト・ヘッダーに発行されます。
POST .../files/data
リクエスト・ヘッダー
Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518 Cookie: dAccessCode-LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518=test12345
リクエスト本文
-----------------------------7dc7c172076a Content-Disposition: form-data; name="parameters" Content-Type: application/json { "parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518" } -----------------------------7dc7c172076a Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt" Content-Type: text/plain This is idcTestNewFileREST.txt v1 -----------------------------7dc7c172076a--
HTTPステータス・コード
HTTP_STATUS = 201
JSONレスポンス
{ "createdBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "createdTime": "2016-06-30T20:09:54Z", "errorCode": "0", "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000000801", "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000000801'.", "id": "D34BA589F6ACC07B6EA371C7B5D17B95F47087F4E518", "mimeType": "text/plain", "modifiedBy": { "displayName": "User BB", "loginName": "userBBLoginName", "id": "U6A0B35B0548F250914D18FDB5D17B95F470", "type": "user" }, "modifiedTime": "2016-06-30T20:09:54Z", "name": "idcTestNewFileREST.txt", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518", "size": "33", "type": "file", "version": "1" }
例4
次の例では、マルチパート・リクエストを使用して、新しいファイルのアップロードをリクエストします。 このファイルは現在のユーザーに所有または共有されていないフォルダ構造にあるため、アクセス拒否エラー・メッセージが返されます。
POST .../files/data
リクエスト・ヘッダー
Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
リクエスト本文
-----------------------------7dc7c172076a Content-Disposition: form-data; name="parameters" Content-Type: application/json { "parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518" } -----------------------------7dc7c172076a Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt" Content-Type: text/plain This is idcTestNewFileREST.txt v1 -----------------------------7dc7c172076a--
HTTPステータス・コード
HTTP_STATUS = 403
JSONレスポンス
{ "errorCode": "-20", "errorKey": "!csUnableToCheckIn,idcTestNewFileREST.txt!csCloudItemInsufficientPrivileges,User BB,fFolderGUID:F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518,CHECKIN_UNIVERSAL", "errorMessage": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. User 'User BB' has insufficient privilege to access fFolderGUID:F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518 with service CHECKIN_UNIVERSAL.", "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518", "title": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. User 'User BB' has insufficient privilege to access fFolderGUID:F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518 with service CHECKIN_UNIVERSAL.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
例5
次の例では、マルチパート・リクエストを使用して、新しいファイルのアップロードをリクエストします。 このファイルは現在のユーザーに所有または共有されていないフォルダ構造にあります。また、アクセス・コードで保護されているパブリック・リンクのみを使用可能です。 アクセス・コードがリクエストの一部として送信されなかったため、エラーが返されます。
POST .../files/data
リクエスト・ヘッダー
Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a LinkID: LF8D36FAFAB4388BECEAC4AEB5D17B95F47087F4E518
リクエスト本文
-----------------------------7dc7c172076a Content-Disposition: form-data; name="parameters" Content-Type: application/json { "parentID":"F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518" } -----------------------------7dc7c172076a Content-Disposition: form-data; name="primaryFile"; filename="idcTestNewFileREST.txt" Content-Type: text/plain This is idcTestNewFileREST.txt v1 -----------------------------7dc7c172076a--
HTTPステータス・コード
HTTP_STATUS = 403
JSONレスポンス
{ "errorCode": "-18", "errorKey": "!csUnableToCheckIn,idcTestNewFileREST.txt!csAccessCodeRequiredForLinkAccess", "errorMessage": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. The access code must be provided to access the link.", "parentID": "F4AB9FC75860ECB429D36BA2B5D17B95F47087F4E518", "title": "Content item 'idcTestNewFileREST.txt' was not successfully checked in. The access code must be provided to access the link.", "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html" }
例6
次の例では、マルチパート・リクエストを使用して新しいファイルをアップロードします。 この例では、グローバル・コレクションCollectionA
のメタデータ値も設定します。
POST .../files/data
リクエスト・ヘッダー
Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a
リクエスト本文
-----------------------------7dc7c172076a Content-Disposition: form-data; name="jsonInputParameters" { "parentID":"F79B040D5393DAC0F3511BBAB5D17B95F47087F4E518" } -----------------------------7dc7c172076a Content-Disposition: form-data; name="primaryFile"; filename="fileWithMetadata.txt" Content-Type: text/plain This is a file containing metadata values. -----------------------------7dc7c172076a Content-Disposition: form-data; name="metadataValues" Content-Type: application/json { "collection": "CollectionA", "fieldA": "valueA", "fieldB": "valueB", "fieldC": "valueC" } -----------------------------7dc7c172076a--
HTTPステータス・コード
HTTP_STATUS = 201
JSONレスポンス
{ "createdBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "createdTime": "2016-07-13T19:47:23Z", "errorCode": "0", "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000001200", "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000001200'.", "id": "D4100E975A8096829C9CCB06B5D17B95F47087F4E518", "metadata": { "CollectionA": { "fieldA": "valueA", "fieldB": "valueB", "fieldC": "valueC" } }, "mimeType": "text/plain", "modifiedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "modifiedTime": "2016-07-13T19:47:23Z", "name": "fileWithMetadata.txt", "ownedBy": { "displayName": "User AA", "loginName": "userAALoginName", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "type": "user" }, "parentID": "F79B040D5393DAC0F3511BBAB5D17B95F47087F4E518", "size": "42", "type": "file", "version": "1" }
例7
次の例では、マルチパート・リクエストを使用して新しいファイルをアップロードします。 このファイルは、現在のユーザーが所有していない、または共有していないフォルダ構造の下にあるため、この例ではapplinkを使用しています。 applink IDとアクセス・トークンはリクエスト・ヘッダーに送信されます。
POST .../files/data
リクエスト・ヘッダー
Content-Type: multipart/form-data; boundary=---------------------------7dc7c172076a appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg== accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ
リクエスト本文
-----------------------------7dc7c172076a Content-Disposition: form-data; name="parameters" Content-Type: application/json { "parentID":"FDC22B65E850730CAA60AF83B5D17B95F47087F4E518" } -----------------------------7dc7c172076a Content-Disposition: form-data; name="primaryFile"; filename="fileViaApplink.txt" Content-Type: text/plain This is fileViaApplink.txt v1 -----------------------------7dc7c172076a--
HTTPステータス・コード
HTTP_STATUS = 201
JSONレスポンス
{ "createdBy": { "displayName": "User BB", "id": "U5083EA1954687218BA6C3D9B5D17B95F470", "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470", "type": "user" }, "createdTime": "2017-06-26T15:29:00Z", "errorCode": "0", "errorKey": "!csServiceStatusMessage_checkin,SOMETHING00004370530000007006", "errorMessage": "Successfully checked in content item 'SOMETHING00004370530000007006'.", "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518", "mimeType": "text/plain", "modifiedBy": { "displayName": "User BB", "id": "U5083EA1954687218BA6C3D9B5D17B95F470", "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470", "type": "user" }, "modifiedTime": "2017-06-26T15:29:00Z", "name": "fileViaApplink.txt", "ownedBy": { "displayName": "User AA", "id": "UEB6AD431E4357AE752CE3F2B5D17B95F470", "loginName": "userAALoginName", "type": "user" }, "parentID": "FDC22B65E850730CAA60AF83B5D17B95F47087F4E518", "size": "29", "type": "file", "version": "1" }