REST API for Content Management 1.1

Get File Accesses

get

/documents/api/1.1/files/{fileId}/accesses

Get information on which users have accessed the specified file.

Request

Supported Media Types

application/json
application/xml

Path Parameters

fileId: Type: string

Required: true

Globally unique identifier (GUID) for the file.

Query Parameters

limit

Type: string

Specify the maximum number of accesses to return. Use this parameter to specify how many items to include on a single page of results. The default is 200.

offset

Type: string

Specify the point at which to begin the list of items from the complete set of items returned for the action. If you do not specify an offset, the returned items begin with the first item in the item list (offset=0).

orderBy

Type: string

The results can be sorted by the fields below. The sort order can be defined as ascending (asc) or descending (desc). The default sort order is ascending.

accessedBy sorts by the user who initiated the activity.
version sorts by version of the item on which activity occurred.
accessType sorts by the type of the access (for example: preview, download).
size sorts by the size of the item accesses.
accessedTime sorts by the time of the access.
clientIP sorts by IP address of the client on which this activity was initiated.
errorCode sorts by the status code of the activity.

Header Parameters

accessToken: Type: string

Applink access token authorizing the current user to access the parent folder or this file. This parameter is mandatory if appLinkID is used. It can be used as accessToken or AccessToken.
appLinkID: Type: string

Applink ID authorizing the current user to access the parent folder or this file. Any time the parameter appLinkID is used, a parameter accessToken must be provided as well. To work, this applink must have at least the contributor role granted. It can be used as appLinkID or AppLinkID.
dAccessCode: Type: string

Access code needed to use protected public links. It needs to be sent as part of a Cookie header in the following format: dAccessCode-<linkID>=<passcodeValue>
linkID: Type: string

Public link ID of a public link authorizing the current user to access this file. It can be used as linkID or LinkID.

Response

Supported Media Types

application/json
application/xml

200 Response

The request was fulfilled.

Body

Root Schema : FileAccessesResponse

Properties

count: Type: string

The number of accesses returned.
errorCode: Type: string

An error code of zero (0) indicates no errors.
hasMore: Type: string

Indicates if all accesses were returned; if all the accesses were returned, this is zero (0).
items: Type: array items

Additional Properties Allowed:

List of File Accesses.
totalCount: Type: string

The total number of accesses for the item.

Nested Schema : items

Type: array

List of File Accesses.

Items

Type: object FileAccessItemsDefinition

Additional Properties Allowed:

Nested Schema : FileAccessItemsDefinition

Properties

accessedBy: Type: object AccessedByUser

Additional Properties Allowed:

User information
accessedTime: Type: string

Date the item was accessed.
accessType: Type: string

Type of the access (for example: preview, download).
clientIP: Type: string

The client IP that accessed the file
errorCode: Type: string

An error code of zero (0) indicates no errors accessing the file.
id: Type: string

Globally unique identifier (GUID) for the file that was accessed.
refererURL: Type: string

The referring URL of the access.
size: Type: string

The size of the accessed file.
version: Type: string

Version of the file that was accessed.

Nested Schema : AccessedByUser

User information

Properties

id: Type: string

Globally unique identifier (GUID) for the user.
loginName: Type: string

The login name for the user.
type: Type: string

Item type user.

Example application/json


{
    "count":"1",
    "errorCode":"0",
    "hasMore":"0",
    "totalCount":"1",
    "type":"access",
    "items":[
        {
            "type":"file",
            "accessType":"download",
            "accessedTime":"2017-05-02T21:23:18.000Z",
            "id":"D574378400573ED9D62B3195T0000000000100000001",
            "version":"1",
            "accessedBy":{
                "id":"U0EAA20910FAF3052ACB79E4T00000000001",
                "displayName":"User AA",
                "type":"user"
            },
            "errorCode":"0",
            "clientIP":"10.10.82.114",
            "refererURL":"https://service1-tenant1:19200/documents/fileview/D1EEF28A920A342E8EC0E39645B3E9DD6490EF9D4696/_Mugs.jpg",
            "size":"53834"
        }
    ]
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have read permission.

404 Response

File ID is not found.

Examples

The following example gets information about the accesses (downloads and previews) for a file.

GET ...files/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/accesses

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "4",
    "errorCode": "0",
    "hasMore": "0",
    "totalCount": "4",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:47:24Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "UC8DCBEBB5C38E0FA2CE33EF45B3E9DD6490",
                "loginName": "tenant1.cecsadmina",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-05-03T21:47:06Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "U971B946D64279E62CCEAA5A45B3E9DD6490",
                "loginName": "tenant1.usera",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/folder/F9D24A8073BF47E5B9B1CAE345B3E9DD64902A090B2E/_accessed",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:46:45Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "U971B946D64279E62CCEAA5A45B3E9DD6490",
                "loginName": "tenant1.usera",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:44:21Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "UC8DCBEBB5C38E0FA2CE33EF45B3E9DD6490",
                "loginName": "tenant1.cecsadmina",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        }
    ]
}

Example 2

The following example gets information about the accesses (downloads and previews) for a file, sorted by accessType. Note that the "preview" types are listed first.

GET ...files/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/accesses?orderBy=accessType

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "4",
    "errorCode": "0",
    "hasMore": "0",
    "totalCount": "4",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:44:21Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "UC8DCBEBB5C38E0FA2CE33EF45B3E9DD6490",
                "loginName": "tenant1.cecsadmina",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:47:24Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "UC8DCBEBB5C38E0FA2CE33EF45B3E9DD6490",
                "loginName": "tenant1.cecsadmina",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:46:45Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "U971B946D64279E62CCEAA5A45B3E9DD6490",
                "loginName": "tenant1.usera",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-05-03T21:47:06Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "U971B946D64279E62CCEAA5A45B3E9DD6490",
                "loginName": "tenant1.usera",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/folder/F9D24A8073BF47E5B9B1CAE345B3E9DD64902A090B2E/_accessed",
            "size": "53834"
        }
    ]
}

Example 3

The following example gets information about the accesses (downloads and previews) for a file, sorted by accessType in ascending order, and limited to 2. Note that only 2 items are returned with count, hasMore, and totalCount set appropriately. The "download" types are listed first.

GET ...files/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/accesses?orderBy=accessType?orderBy=accessType:asc&limit=2

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "2",
    "errorCode": "0",
    "hasMore": "1",
    "totalCount": "4",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-05-03T21:47:06Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "U971B946D64279E62CCEAA5A45B3E9DD6490",
                "loginName": "tenant1.usera",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/folder/F9D24A8073BF47E5B9B1CAE345B3E9DD64902A090B2E/_accessed",
            "size": "53834"
        },
        {
            "type": "file",
            "accessType": "preview",
            "accessedTime": "2017-05-03T21:47:24Z",
            "id": "D28824DCD6CB04122318CE9845B3E9DD64902A090B2E",
            "version": "1",
            "accessedBy": {
                "id": "UC8DCBEBB5C38E0FA2CE33EF45B3E9DD6490",
                "loginName": "tenant1.cecsadmina",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.148.63",
            "refererURL": "https://service1-tenant1.hourly.gemini.shared.osn.oraclecorp.com:19201/documents/fileview/D28824DCD6CB04122318CE9845B3E9DD64902A090B2E/_Mugs.jpg",
            "size": "53834"
        }
    ]
}

Example 4

The following example gets information about the accesses (downloads and previews) for a file. The example uses an applink ID because this file is under a folder structure not owned by or shared with the current user. The applink ID and access token are submitted in the request header.

GET ...files/DED694950C14AFF280419F9AB5D17B95F47087F4E518/accesses?limit=2

Request Header

appLinkID: LF5Bxj4TPo_p4n4qWn0tbKTicR2cTUJKv7X_ng9E7ry93rRuDokPqS1d6-wKwhb_wtcGYFDsI_cNMxeKQ-HR-FXQhiVoGRTYM_MPZY8qpICfYU94mmnMjM_cvsRhKMzc0NJgvwEJfqqDwPsAVrhc8cmg==
accessToken: 352FpiMmW66PeYI1Gh5b83I9CXRwZhLfYAu4TXdqpzD8uNKUBMZVVJ3ZvivUW8kQ

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "2",
    "errorCode": "0",
    "hasMore": "1",
    "totalCount": "13",
    "type": "access",
    "items": [
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-06-29T16:35:24Z",
            "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
            "version": "1",
            "accessedBy": {
                "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
                "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.181.1",
            "size": "29"
        },
        {
            "type": "file",
            "accessType": "download",
            "accessedTime": "2017-06-28T20:27:26Z",
            "id": "DED694950C14AFF280419F9AB5D17B95F47087F4E518",
            "version": "1",
            "accessedBy": {
                "id": "U5083EA1954687218BA6C3D9B5D17B95F470",
                "loginName": "U5083EA1954687218BA6C3D9B5D17B95F470",
                "type": "user"
            },
            "errorCode": "0",
            "clientIP": "10.154.110.138",
            "size": "29"
        }
    ]
}