Salesforce BULK API v2

Salesforce online olarak kullanılan bir CRM platformudur. Bu platform, Dünya çapında 150.000'den fazla büyük-küçük ölçekli şirketlerce kullanılmaktadır. 

Saleforce, müşterilerin daha kolay entegre olabilmesi için; SOAP, REST gibi servislerini geliştirciler ile paylaşmıştır. Bugün, Salesforce'a büyük verilerin aktarılmasını sağlayan REST servisinden yani Bulk API'dan bahsedeceğiz. Bulk API, Saleforce sistemine büyük verilerin hızlı ve performanslı bir şekilde yüklenmesini sağlayan REST servisidir. Bu yazımızda ele alacağımız versiyon, Bulk API v2 versiyonudur. 

Bulk API v2, Bulk API v1'e göre daha az işlem ile insert, update, delete ve upsert süreçlerini yürütür. Bulk API v2'nin özelliklerinden bazıları aşağıdaki gibidir.

OAuth 2.0 Desteği

Bulk API v2, diğer Salesforce REST API'leri gibi OAuth akışlarının hepsini desteklemektedir. 

Otomatik Dosya Bölümleme

Bulk API v2 ile gelen bir diğer özellik ise gönderilen büyük boyutlu dosyaların otomatik olarak batchlere ayrılmasıdır. Bulk API v1'de bu işlemi de geliştirici yapıyordu ve yapılan iş süreci oldukça uzatıyordu. Bu başlığın detaylarına Bulk API v2 - Bulk API v1 karşılaştırmasında detaylıca bakacağız.

Günlük Kayıt Limiti

Bulk API v2 ile artık kayıtlar job bazlı değil gönderilen kayıt satırına göre limitlendirilmiştir. Bu limit 24 saat için 100 milyon kayıttır.

Bulk API v2'de veriler sadece CSV olarak gönderilir. Bunun sebebi yüksek boyutlu dosyalarda, veriyi olabildiğince ham halinde tutmaktır. Örneğin bir XML dosyasında asıl veriye ek olarak birçok XML tagıda olacaktır. Aynısı JSON içinde geçerli denebilir. 

Burada karşımıza çıkan en önemli sorulardan biri neden Bulk API v1 yerine Bulk API v2 kullanmalıyız olacaktır.

Bulk API v1 ve Bulk API v2 karşılaştırmasına gelin yakından bakalım.

Öncelikle Bulk API v1'den bahsedelim. Bulk API v1 ile geliştirme yapıyorsanız aşağıdaki adımları uygulamanız gerekmektedir.

1. Authenticated olan bir Session Id servisten alınır. Bunun içinde farklı bir SOAP API kullanılır.
2. Bulk API v1 Job'ı oluşturulur.
3. Job'a gönderilen data batchlere ayrılır.. Buradaki işlem yapılacak senaryoya göre karmaşıklaşabilir. 
   • a. Veriler Bulk API v1 batch boyutlarına göre ayrılır,
   • b. İhtiyacınıza göre özel bir işleme yöntemi seçilir. Örneğin comperasion veya PK Chunking.
   • c. Karşılaşılabilecek sorunlar için veri analiz edilir. Ne gibi işlemler veri akışını yavaşlatır, neden hata alır vs.
   • d. Toplu olarak veriyi işlemek zaman aşımlarına neden olabilir bu yüzden veriler minimize edilmeli.
   • e. Tüm bu işlemlerden sonra batchlerinizin işlenmesi uzun süreler alıyorsa, yaptığınız analizleri ve geliştirmeleri yeniden gözden geçirmeniz gerek.
4. Veri oluşturulan batchlere yüklenir.
5. Verinin düzgün bir şekilde yüklendiğinden emin olunur.
6. Oluşturulan Job kapatılır.
7. Job'ın durumu kontrol edilir.
8. Eğer Job başarılı bir şekilde tamamlanmışsa, süreç bitti sayılır.
9. Eğer Job tamamlanmış fakat işlem sürecinde hatalarla karşılaşılmışsa, job içindeki her bir batche bakılır. Batch için başarılı ve başarısız kayıtlar toplanır ve neden hata aldığı tespit edilir. Bu işlem sonrasında eğer gerekliyse, toplanan kayıtlar yeni bir job oluşturularak tekrar gönderilir.

Aynı işlemi bir de Bulk API v2 ile yapalım.

1. OAuth servis ile Authenticate olunur.
2. Bulk API v2 Job'ı oluşturulur.
3. Tüm data yüklenir.
4. Oluşturulan Job kapatılır.
5. Job'ın durumu kontrol edilir.
6. Eğer Job başarılı bir şekilde tamamlanmışsa, süreç bitti sayılır.
7. Eğer Job tamamlanmış fakat işlem sürecinde hata alınmışsa, hatalı kayıtların listesine bakılır. Bunun için ayrı bir API çağırmanız gerekmektedir. Başarılı ve başarısız kayıtlar toplanır ve neden hata aldığı tespit edilir. Bu işlem sonrasında eğer gerekliyse, toplanan kayıtlar yeni bir job oluşturularak tekrar gönderilir.

Postman uygulaması üzerinden yapabileceğimiz Bulk API v2 işlemlerini inceleyelim.

1. Job oluşturma

Job oluşturmak için, /services/data/v{{apiVersion}}/jobs/ingest/ servisine POST methodu ile istek atılır.

Örnek İstek : 

{

    "object": "Contact",

    "contentType": "CSV",

    "operation": "insert"

}

2. Veriyi yüklemek

Bir önceki adımda gönderdiğimiz istekten dönen cevabın içindeki JobId değeri alınır.Buradaki JobId değeri veriyi yüklerken kullanacağımız servis için gerekli. 

Veriyi yüklemek için, /services/data/v{{apiVersion}}/jobs/ingest/{{jobId}}/batches servisine PUT methodu ile istek atılır.

Header bilgisindeki Content-Type değeri text/csv olmalıdır.

Örnek İstek

FirstName,LastName,Title,Email

John, Doe,Bulk API User,testuser@mdpgroup.com

3. Job’ı kapatmak

Veri gönderim işlemi tamamlandıktan sonra Job’ı kapatmamız gerekiyor. İstek atacağımzı servis için yine aynı JobID değeri kullanılmalıdır.  

Job’ı kapatmak için, /services/data/v{{apiVersion}}/jobs/ingest/{{jobId}} servisine PATCH methodu ile istek atılır.

4. Job durumunu kontrol etmek

Job’ı kapattıktan sonra durumunu kontrol etmemiz gerekiyor. 

Job durumunu kontrol etmek için : /services/data/v{{apiVersion}}/jobs/ingest/{{jobId}} adresine GET methodu ile istek atılır.

5. Hatalı Kayıtların Listesi

Herhangi bir kayıtta hata oluşup oluşmadığını görmek için /services/data/v{{apiVersion}}/jobs/ingest/{{jobId}}/failedResults servisine GET methodu ile istek atılır.

Yapılacak işlemlerin tamamı bu kadar. Bulk API v1’e göre daha kolay ve daha hızlı bir şekilde geliştirmemizi tamamlayabildik. 

Bulk API v2’yi daha detaylı incelemek için : https://developer.salesforce.com/docs/atlas.en-us.api_bulk_v2.meta/api_bulk_v2/introduction_bulk_api_2.htm  <Bulk API 2.0 Developer Guide>

Adresini ziyaret edebilirsiniz.

Bu işlemleri MDP Salesforce Adapter ile tek adımda yapabilirsiniz.

Veri yüklemek, oluşturulan Jobların kontrolü, Joblara ait sonuçların kontrolleri hatta SOQL desteği ile verilerinizi Salesforce ortamından hızlıca çekebilmeniz için MDP Salesforce Adapter kullanabilirsiniz.

MDP Salesforce Adapter çözümünün detaylarına aşağıdaki adresten ulaşabilirsiniz.

MDP Salesforce Bulk API v2 Adapter

Ayrıca SAP Community'de paylaştığımız MDP Salesforce Bulk API v2 Adapter başlıklı blog yazımızı incelemek için de aşağıdaki adresi ziyaret edebilirisiniz.

SAP Community : The MDP Salesforce Bulk API v2 Adapter for SAP Cloud Platform Integration

 

­