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 that you intend to push into a Push source or security identity provider. You’ll typically use a file container when you want to push:
This article provides an overview of the Create a file container
request.
Create a file container
request in the context of a batch update sequence and illustrating how the Coveo indexing pipeline handles the batch update.Request template
US East region
POST https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
Accept: application/json
Authorization: Bearer <MyAccessToken>
Canada region
POST https://api-ca.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
Accept: application/json
Authorization: Bearer <MyAccessToken>
Ireland region
POST https://api-eu.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
Accept: application/json
Authorization: Bearer <MyAccessToken>
Australia region
POST https://api-au.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/files?useVirtualHostedStyleUrl=<true|false> HTTP/1.1
Accept: application/json
Authorization: Bearer <MyAccessToken>
Request parameters:
Parameters
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 a virtual hosted-style URL, such ascoveo-nprod-customerdata.s3.amazonaws.com/...
. The default value is currentlyfalse
, which means that the service returns path-style URLs, such ass3.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 a Push source API key that grants the set of privileges required to push items to your source.
Request body:
{}
Successful response: 201 Created
The body of a successful response contains important information about the temporary, private, and encrypted Amazon S3 file container that you just created:
{
"uploadUri": "<UPLOAD-URI>",
"fileId": "<FILE_ID>",
"requiredHeaders": {
"x-amz-server-side-encryption": "AES256",
"Content-Type": "application/octet-stream"
}
}
The uploadUri property contains a pre-signed URI to
make a PUT request to when pushing item or security identity data.
|
|||
The fileId property contains the unique identifier of your file container. |
|||
The requiredHeaders property contains the required HTTP headers for sending
a PUT request to the uploadUri . |
Path-style URL deprecation
Amazon is deprecating path-style URLs, such as s3.amazonaws.com/coveo-nprod-customerdata/...
, in favour of virtual hosted-style URLs, such as 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 behavior.
Virtual hosted-style URLs let you 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-nhipaa-customerdata.s3.amazonaws.com
.
Sample request
The following example shows how to create a file container for a Coveo organization in the US East region.
POST https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/files?useVirtualHostedStyleUrl=true HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
Request body:
{}
Response:
{
"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"
}
}