[SalesForce] Understanding the implementation of “Use Bulk API” Trailhead

From our comment thread on the OP:

1. You need to configure an external Id field on your object; this will generally by the primary key used by your external system with which you are syncing. See http://na1.salesforce.com/help/doc/en/faq_import_general_what_is_an_external.htm and http://na1.salesforce.com/help/doc/en/custom_field_attributes.htm
2. Change your operation to upsert and ensure the external Id is provided in your data file.
3. Edit Add the external Id to your XML (see Update 2 below)

Update 1

I don't think there are any changes to the HTTP POST request. Sample updated CSV as requested (some values shortened for improved formatting):

Id,FirstName,LastName,Department,Birthdate,Description, My_External_Id__c
"003i000000EpehQ","Tomas","Jones","MKG","1940-06-07Z","Awesome", "ExternalPrimaryKey1"
"003i000000EpYI7","Ian","Dury","R&D","","Expert", "ExternalPrimaryKey2"

Update 2

I found the XML definition needed to start the job here. Using cURL with the job.txt example provided by Salesforce, your XML should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<jobInfo xmlns="http://www.force.com/2009/06/asyncapi/dataload">
<operation>upsert</operation>
<object>Contact</object>
<externalIdFieldName>My_External_Id__c</externalIdFieldName>
<contentType>CSV</contentType>
</jobInfo>

Note that capitalization and the order of the elements is important; if you put <externalIdFieldName> after <contentType> you will get a HTTP 400 error message stating it was unable to parse the job. After successfully submitting the job you will get an XML response with the job id, operation, object, etc... (see page 6 in the previously linked PDF.)

The sObject tree is only for the REST API, not the Bulk API. While they both use a REST-ful nature, only the REST API supports the sObject tree. This generally means you have to upload records in batches of 200, with a tree no more than 5 levels deep.

You can still use JSON structures with the bulk API, but it follows a slightly different format, outlined in Bulk API Relationships, and in other related documents in the Developer's Guide.

An example of using a parent-child relationship follows:

[{
  "FirstName" : "Ray",
  "LastName" : "Riordan",
  "ReportsTo" : { "Email" : "rwilliams@salesforcesample.com" }
}]

In this case, a contact named Ray Riordan is linked to a Reports To contact matching the email of rwilliams@salesforcesample.com. This is similar in nature to how the classic SOAP API can handle an indexed field relationship. However, as you'll notice, it's not the same as using the sObject tree, which relates records together using their relationship name.

The main difference between the two APIs is that the Bulk API is asynchronous and is better for many thousands of records, while the REST API is synchronous and better for real-time results on a smaller set of records. If you need to upload many thousands of records, use the Bulk API, otherwise use the REST API.