Create a file container
Create a file container
A file container is a temporary, private, and encrypted Amazon S3 data structure you can use to safely upload content you intend to push into a Push source or security identity provider. You will typically use a file container when you want to push:
-
Large item data (see Using the compressedBinaryDataFileId Property)
-
Batches of items (see Manage batches of items in a Push source)
-
Batches of security identities (see Manage Batches of Security Identities)
Use the Create a file container operation to create an Amazon S3 file container for a specific Coveo organization:
Request template
POST https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>
Payload
{}
In the request path:
-
Replace
<MyOrganizationId>
with the ID of the target Coveo organization (see Retrieve the organization ID).
In the query string:
-
Optionally, set
useVirtualHostedStyleUrl
totrue
if you want the service to return the URL in virtual hosted-style (e.g.,coveo-nprod-customerdata.s3.amazonaws.com/...
). Default value is currentlyfalse
, which means that the service returns path-style URLs (e.g.,s3.amazonaws.com/coveo-nprod-customerdata/...
).The
useVirtualHostedStyleUrl
query string parameter will soon be deprecated as part of the path-style URL deprecation. From this point onwards, the service will only return virtual hosted-style URLs.
In the Authorization
HTTP header:
-
Replace
<MyAccessToken>
with an access token that grants Organization - View privileges in the target Coveo organization (see Get your Coveo access token, Create an API key, Manage privileges, and Get the privileges of an access token).
The body of a successful response contains important information about the temporary, private, and encrypted Amazon S3 file container you just created:
-
The
uploadUri
property contains a pre-signed URI to which you can send aPUT
request whose binary content must be your request body or item data.Notes-
The Amazon S3 file container applies AES-256 server side encryption to your data (see Advanced Encryption Standard).
-
The file container is automatically deleted as soon as its content has been successfully forwarded to the service.
-
The
uploadUri
automatically expires after 60 minutes.
Therefore, it’s perfectly safe to upload sensitive information into the Amazon S3 file container.
-
-
The
fileId
property contains the unique identifier of your file container. -
The
requiredHeaders
property contains the required HTTP headers for sending aPUT
request to theuploadUri
.
Path-style URL deprecation
Amazon is deprecating path-style URLs (e.g., s3.amazonaws.com/coveo-nprod-customerdata/...
) in favour of virtual hosted-style URLs (e.g., coveo-nprod-customerdata.s3.amazonaws.com/...
).
Accordingly, the Push API will also deprecate path-style URLs.
You can already test and use the new hosted-style URL format by setting the useVirtualHostedStyleUrl
query parameter to true
.
If you’re using the Crawling Module or Coveo for Sitecore, you can update to the latest version to test the new behaviour.
Virtual hosted-style URLs allow you to be more precise regarding the list of outbound URL addresses to allow.
For example, if your primary deployment region is US East, you can allowlist coveo-nprod-customerdata.s3.amazonaws.com
rather than s3.amazonaws.com
.
The following table lists the virtual hosted-style domain for each primary region:
Main region | Virtual hosted-style domain |
---|---|
US East |
|
Canada |
|
Ireland |
|
Australia |
|
For HIPAA organizations, the virtual hosted-style domain name is coveo-nhip-customerdata.s3.amazonaws.com
.
Sample request
Creating a file container for a specific Coveo organization
POST https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/files?useVirtualHostedStyleUrl=true HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Payload
{}
Successful response - 201 Created
{
"uploadUri": "link:https://coveo-nprod-customerdata.s3.amazonaws.com/proda/blobstore/mycoveocloudv2organizationg8tp8wu3/b5e8767e-8f0d-4a89-9095-1127915c89c7[...]",
"fileId": "b5e8767e-8f0d-4a89-9095-1127915c89c7",
"requiredHeaders": {
"x-amz-server-side-encryption": "AES256",
"Content-Type": "application/octet-stream"
}
}