Add or update a single item in a Push source
Add or update a single item in a Push source
Being able to add or update a single item in a Push source can be useful when you’re testing the service or to perform a small content update.
This article provides an overview of the Add or update an item
HTTP request, with details and examples for basic and more complex cases.
Add or update an item
Push API request (highlighted) as it progresses through the Coveo indexing pipeline.Add or update a basic public item
One of the most rudimentary requests you can perform with the Push API is to add or update a single, uncompressed, raw textual item in a public Push source.
Refer to the following Add or update an item
HTTP request template and sample to add an item to your public Push source.
Request template
PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/sources/<MySourceId>/documents?documentId=<MyItemURI> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>
Parameters
In the request path:
-
Replace
<MyOrganizationId>
with the ID of the target Coveo organization (see Retrieving the ID of a Coveo organization). -
Replace
<MySourceId>
with the ID of the target public Push source (see Create a Push source).
In the query string:
-
Replace
<MyItemURI>
with the URL-encoded URI of the public item to add or update in the target public Push source (for example,file%3A%2F%2Ffolder%2FdummyItem.html
).
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:
{
"data": <MyItemData>
}
Parameters
Replace <MyItemData>
with the raw textual data corresponding to the public item to add or update in the target public Push source (for example, "This is a sample raw textual \"Data\" string."
).
Your total request body size must not exceed 6 MB (see Push API limits - Request size limits).
You must properly escape reserved JSON characters (for example, newline, tab, double quote, backslash, etc.) in your data
string (see Using the data property).
Successful response: 202 Accepted
null
A successful response indicates that the operation was successfully forwarded to the service and that the item is now enqueued to be processed by the document processing manager (DPM). This doesn’t imply that the item was successfully added or updated in the target Push source (see About the Push API processing delay).
|
To maximize efficiency and comply with API consumption limits, don’t use this request repeatedly to add or update many items in a Push source (that is, to perform a large scale content update). Use batch update requests instead. |
Sample request
The following example shows how to push an item whose raw textual data is HTML formatted.
PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy/documents?documentId=file%3A%2F%2Ffolder%2FdummyItem.html HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Request body:
{
"data": "<html><body><h1>Dummy item</h1><p>This is dummy raw textual item data</p></body></html>"
}
Add or update a complex secured item
After you create a secured Push source and set up a security identity provider for your secured Push source, you can use the Push API to add a raw text item with access permissions to your source.
|
Leading practice: Perform a security identity update
Whenever you’re about to add or update content in a secured Push source, you should perform a security identity update on the security identity provider to ensure that the security identities referenced in item permission models are up to date in the security identity cache (see Manage security identities in a security identity provider). |
Use the following Add or update an item
HTTP request template and sample to add a secured item with some metadata to your secured Push source.
Request template
PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/sources/<MySourceId>/documents?documentId=<MyItemURI>&compressionType=<MyCompressionType> HTTP/1.1
Content-Type: application/json
Accept: application/json:
Authorization: Bearer <MyAccessToken>
Parameters
In the request path:
-
Replace
<MyOrganizationId>
with the actual ID of the target Coveo organization (see Retrieve the organization ID). -
Replace
<MySourceId>
with the actual ID of the target Push source.
In the query string:
-
Replace
<MyItemURI>
with the URL-encoded URI of the item to add or update in the target Push source (for example,file%3A%2F%2Ffolder%2FdummyItem.html
). -
If you’re using the
compressedBinaryData
or thecompressedBinaryDataFileId
request body property to push item data, replace<MyCompressionType>
with the actual compression algorithm that was applied to the item data (UNCOMPRESSED
,DEFLATE
,GZIP
,LZMA
, orZLIB
).compressionType
values are case sensitive. If you’re not using thecompressedBinaryData
or thecompressedBinaryDataFileId
request body properties, don’t include thecompressionType
parameter in your query string.
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:
{
<MyItemMetadata>,
<MyItemDataProperty>: <MyItemDataOrFileId>,
"fileExtension": <MyItemDataFileExtension>,
"parentId": <MyItemParentId>,
"permissions": <MyItemPermissionModel>
}
Parameters
-
Replace
<MyItemMetadata>
with any number of arbitrary metadata key-values you want to include with the item you’re adding or updating in the target Push source (see About Push source item metadata). -
Replace
<MyItemDataProperty>
with the property you want to use to push the item data (data
,compressedBinaryData
, orcompressedBinaryFileId
). -
Replace
<MyItemDataOrFileId>
accordingly (see Pushing item data). -
(Leading practice) Replace
<MyItemDataFileExtension>
with the actual file extension which the Push API should use to interpret the item data (for example,.txt
,.html
, etc.). This value must include a preceding dot (.
) character. -
Optionally, to establish a parent-child relationship between the item and other items in the same Push source, replace
<MyItemParentId>
with the@documentId
of the parent item, or by the@documentId
of the item your are adding or updating if this item itself is the parent (see About the parentId property). -
If the target Push source is secured, replace
<MyItemPermissionModel>
with a valid permission model for the pushed item.See:
Successful Response: 202 Accepted
null
A successful response indicates that the operation was successfully forwarded to the service and that the item is now enqueued to be processed by the document processing manager (DPM). This doesn’t imply that the item was successfully added or updated in the target Push source (see About the Push API processing delay).
|
Leading practice: Update the status of your Push source
If you set your Push source to an active status before, you should consider setting it back to the |
|
To maximize efficiency and comply with API consumption limits, don’t use this operation repetitively to add or update many items in a Push source (that is, to perform a large scale content update). Use the batch operation instead. |
Sample request
The following example shows how to push a secured item whose data was previously uploaded to a file container.
PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy/documents?documentId=file%3A%2F%2Ffolder%2FdummyItem.html&compressionType=Deflate HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************
Request body:
{
"date": "2017-11-08T12:18:41.666Z",
"documenttype": "HTML",
"filename": "dummyItem.html",
"isfrequentlyupdated": true,
"language": [
"English"
],
"permanentid": "my9837423dummy2039482permanent234id",
"sourcetype": "Push",
"title": "My Dummy Item",
"compressedBinaryDataFileId": "b5e8767e-8f0d-4a89-9095-1127915c89c7",
"parentId": "file://myParentDummyItem.html",
"permissions": [
{
"allowAnonymous": false,
"allowedPermissions": [
{
"identity": "SampleTeam1",
"identityType": "Group",
},
{
"identity": "SampleGroup1",
"identityType": "VirtualGroup"
}
],
"deniedPermissions": [
{
"identity": "bjones@example.com",
"identityType": "User"
}
]
},
{
"allowAnonymous": false,
"allowedPermissions": [
{
"identity": "emitchell@example.com",
"identityType": "User"
}
]
}
]
}