Walkthrough: Creating and updating index documents in two locales using the Ingestion API

After an administrator configures an API push source in Sitecore Search, you can use the Ingestion API to add documents to that index and, later, update or delete documents.

Note

This walkthrough describes how to create index documents by passing attribute values. You can also create index documents by passing document extractors.

This walkthrough describes how to use the Ingestion API in the following scenario:

You want to create documents in the English (en_us) and French (fr_fr) locales. The French document is a translation of the English document.

Note

You are able to create index documents in two locales because an administrator has configured the API push source to have two locales.
You want each document to have the ID, title, description, image_url, and content_type attributes.

This walkthrough describes how to:

Use the Ingestion API to create index documents in two locales.
Use the Ingestion API to edit index documents in both locales.

Before you begin

Ensure that an administrator does the following:

In Search, add all attributes required by the index documents you are going to create.
Create and publish a source with ENABLE INCREMENTAL UPDATES turned on. You will use the ID of this source in Ingestion API calls.

Note

This prerequisite does not apply if the source is an API push source.
Get an API key with the ingestion scope. You can see this API key in the Developer Resources > API Access section of Search.

Note

This prerequisite does not apply if your implementation uses a subdomain.

Use the Ingestion API to create index documents in two locales

To create a document with the Ingestion API, use the POST method on the Create Document endpoint and pass all required parameters. Make two calls, one for the English (US) document and one for the France (FR) document, and ensure you pass the same document ID for both documents.

Note

Always assign the same ID to index documents with the same content but different locales. This ensures that rules like pin, boost, or bury, for example, apply to all locales.

To use the Ingestion API to create documents:

To add the English (US) document, make a POST call to the Create Document endpoint and specify the locale as en_us. In the request URL, add the ID of the push source and your domain ID. In the request body, add the index document ID and the attributes you want the index document to have.

Here's a sample POST CURL call:

RequestResponse

curl --location 'https://discover.sitecorecloud.io/ingestion/v1/domains/110525450/sources/879132/entities/content/documents?locale=en_us' \
--header 'Content-Type: application/json' \
--header 'Authorization: 01-dsd5-2703c7fb73cfcfd0778dhd439bd9a12444'\
--data '{
    "document": {
        "id": "push_source_test_123",
        "fields": {
            "title": "English title",
            "description": "English description",
            "type": "blog",
            "image_url": "www.myimage.com",
        }
    }
}'

To add the French (FR) document, make a POST call to the Create Document endpoint and specify the locale as fr_fr. In the path, add the source ID of the push source, your domain ID, and the locale. In the request body, add the index document ID and the attributes you want the index document to have.

Here's a sample POST CURL call:

RequestResponse

curl --location 'https://discover.sitecorecloud.io/ingestion/v1/domains/110525450/sources/879132/entities/content/documents?locale=fr_fr' \
--header 'Content-Type: application/json' \
--header 'Authorization: 01-dsd5-2703c7fb73cfcfd0778dhd439bd9a12444'\
--data '{
    "document": {
        "id": "push_source_test_123",
        "fields": {
            "title": "French title",
            "description": "French description",
            "type": "blog",
            "image_url": "www.myimage.com"
        }
    }
}'

Use the Ingestion API to edit index documents in both locales

You want to edit the English (US) and French (FR) index documents to change the image_url from www.myimage.com to www.newimage.com . To do this, use the PATCH method on the Partial Update Document endpoint and pass both locales as query parameters. You can do this in a single call.

Here's a sample PATCH CURL call:

RequestResponse

curl --location 'https://discover.sitecorecloud.io/ingestion/v1/domains/110525450/sources/879132/entities/content/documents/push_source_test_123?locale=en_us&locale=fr_fr' \
--header 'Content-Type: application/json' \
--header 'Authorization: 01-dsd5-2703c7fb73cfcfd0778dhd439bd9a12444'\
--data '{
    "document": {
        "id": "push_source_test_123",
        "fields": {
        "image_url": "www.newimage.com"
        }
    }
}'

Do you have some feedback for us?

If you have suggestions for improving this article,