Находясь в пространстве «Программное обеспечение как услуга», вы должны восхищаться тем, чего удалось достичь Salesforce. Было бы трудно поспорить с их успехом, особенно на уровне корпоративных клиентов.

Несмотря на то, что у них есть один из самых отлаженных и известных подходов к продажам в программном обеспечении, создается ощущение, что когда компания достигает определенного размера, они просто решают, что пришло время использовать Salesforce. Именно поэтому, если у вас есть продукт, работающий в сфере продаж и маркетинга, у вас есть огромные возможности для подключения к сообществу и экосистеме Salesforce.

Например, мы создали интеграцию GoSquared с Salesforce, чтобы фиксировать поведение лидов на сайте, когда они просматривают ваш веб-сайт (например, когда лид просматривает вашу страницу с ценами или смотрит веб-семинар), и отправлять эту информацию непосредственно в Salesforce. готов к тому, чтобы ваша команда по продажам могла действовать в рамках существующего рабочего процесса.

Изучение экосистемы разработчиков Salesforce

С компанией, которая имеет широкий и глубокий продукт, который предлагает Salesforce, всегда будут плюсы и минусы, чтобы разобраться в их документации и терминологии.

У них невероятное сообщество разработчиков, включая собственные форумы в стиле Stackoverflow. Если вы столкнулись с препятствием, скорее всего, кто-то сталкивался с ним до вас, и вы можете найти задокументированное решение.

Точно так же у них есть чрезвычайно надежная платформа электронного обучения с треками, которые вы можете пройти по множеству различных предметов, чтобы быстро освоить большую часть их терминологии и принципов.

Однако может быть огромное количество контента, который нужно просеять, и это может занять невероятно много времени, особенно если создание и разработка на платформе Salesforce не будет основной обязанностью вашей работы!

Этот пост в блоге действительно посвящен общению на самом базовом уровне ключевых концепций, необходимых для создания базовой интеграции Salesforce REST API.

Интеграция Salesforce API и приложение Salesforce

Важно подчеркнуть разницу между интеграцией Salesforce API и приложением Salesforce, которое вы найдете на их AppExchange (по сути, в магазине приложений Salesforce).

Размещение приложения в Salesforce AppExchange даст вам возможность встроить свой продукт непосредственно в платформу Salesforce. Например, визуализация данных вашего продукта непосредственно в компоненте Salesforce. Несмотря на очевидные преимущества присутствия в этой экосистеме, важно отметить, что с этим связаны некоторые затраты.

Интеграция Rest API намного проще и в основном ориентирована на отправку данных из вашего приложения и получение данных из Salesforce. В настоящее время с этим типом интеграции не взимается никаких затрат, однако стоит отметить, что интеграция REST доступна только для пользователей Salesforce в рамках их корпоративных тарифных планов (есть возможность получить доступ к REST API в версиях Professional и Group, но это требует внесения вашего приложения в белый список).

Для целей этого поста наш пример интеграции REST API будет очень простым. В нашем приложении будут данные о клиентах, которые мы хотим отправить в Salesforce, и в Salesforce будут данные о клиентах, которые мы хотим получить.

По сути, наша интеграция REST API должна будет выполнять 3 важные вещи:

  1. Разрешить пользователю нашего приложения разрешать нам доступ и передачу его данных Salesforce от его имени.
  2. Разрешить пользователю отправлять данные из нашего приложения в Salesforce.
  3. Разрешить пользователю извлекать данные Salesforce для использования в нашем приложении.

Подготовка к работе с Salesforce

Создайте бесплатную учетную запись разработчика

Начните с получения бесплатной учетной записи разработчика Salesforce.

Учетные записи разработчиков Salesforce великолепны и в значительной степени дают вам работающую организацию Salesforce (организация — это терминология Salesforce для учетной записи), поэтому вы можете почувствовать интерфейс и даже добавлять пользователей и управлять ими.

Настройте связанное приложение

После того как вы настроите учетную запись разработчика, вам нужно настроить подключенное приложение. Связанные приложения могут предлагать множество функций, и иногда это может затруднить их понимание.

Для целей этого и того, как мы собираемся его использовать, проще всего думать о подключенном приложении как о небольшом приложении, которое находится в инфраструктуре Salesforce, на которую вы указываете свою интеграцию. Он отвечает за управление аутентификацией, а также за маршрутизацию запросов к соответствующим экземплярам клиента.

Настроив учетную запись разработчика Salesforce, вы можете настроить подключенное приложение, щелкнув значок Настройка в правом верхнем меню навигации и выбрав Настройка.

Введите Диспетчер приложений в поле Быстрый поиск, а затем выберите Диспетчер приложений.

1. Нажмите Новое связанное приложение.

2. В форме «Новое связанное приложение» заполните:

В разделе Основная информация:

  1. Имя приложения для подключения: YourAppName.
  2. Имя API: оно автоматически станет «YourAppName».
  3. Контактный адрес электронной почты: введите свой адрес электронной почты.

В разделе API (включить настройки OAuth):

  1. Установите флажок Включить настройки OAuth.
  2. URL-адрес обратного вызова: введите URL-адрес обратного вызова, например: https://www.yourappname.com/api/callback

Это будет URL-адрес, на который Salesforce отправляет POST, когда пользователь разрешает вашему приложению доступ к своим данным. Это будет включать в себя токен доступа и запроса (мы объясним это немного подробнее ниже, но они необходимы для отправки и получения данных). Поэтому, если у вас его еще нет, вам нужно будет настроить конечную точку, роль которой заключается в получении и обработке этого запроса.

В разделе Выбранные области действия OAuth:

  1. Выберите Доступ к данным и управление ими (API).
  2. Нажмите Добавить.

После того как вы настроите свое приложение, вам будет предоставлен Ключ потребителя и Секрет потребителя для вашего приложения.

Базовый поток данных Salesforce Oauth

Когда подключенное приложение настроено, удобно получить представление о том, как работает поток данных.

Для начала ваш пользователь направляется на конечную точку авторизации Saleforce.com, где он входит в систему и подтверждает доступ вашего приложения к своим данным.

После успешной авторизации Salesforce отправляет ответ с токеном доступа и токеном обновления.

Токен доступа должен передаваться в заголовке всех запросов API на получение данных. У этого токена есть дата истечения срока действия, и он будет действовать всегда. По умолчанию подключенные приложения имеют маркер доступа со сроком действия 15 минут (в соответствии с настройками сеансов в настройках Salesforce).

Токен обновления используется для получения действительного токена доступа (например, по истечении срока действия текущего токена доступа). Вы можете изменить настройки истечения срока действия для этого, но вы также можете установить, что это никогда не истечет, только когда оно будет отозвано.

Примеры вызовов API:

Чтобы сделать первоначальный запрос авторизации для пользователя, чтобы предоставить вашему приложению доступ к своим данным (именно здесь ваш пользователь первоначально направляется на конечную точку авторизации Saleforce.com и входит в систему), вы должны сделать следующий запрос. client_id в приведенном ниже вызове будет вашим идентификатором потребителя из связанного приложения. redirect_uri будет URL обратного вызова.

curl https://login.salesforce.com/services/oauth2/authorize?response_type=code &client_id=YOURCONSUMERID&redirect_uri=https://www.yourappname.com/api/callback

Успешный ответ на это перенаправит страницу на страницу входа в систему Salesforce, где пользователь сможет войти и пройти аутентификацию. После того как Salesforce подтвердит, что клиент разрешил вашему приложению доступ к своим данным, браузер конечного пользователя перенаправляется на URL-адрес обратного вызова, указанный вами в параметре redirect_uri. Затем Salesforce добавит код авторизации к URL-адресу перенаправления. Их запрос будет выглядеть примерно так, как показано ниже.

https://www.yourappname.com/api/callback?code=aWekysIEeqM9PiThEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D

Вы будете использовать это значение для параметра code при отправке запроса к конечной точке токена Salesforce для получения вашего токена доступа и обновления.

Пример запроса:

curl login.salesforce.com/services/oauth2/token?grant_type=authorization_code&redirect_uri=https://www.yourappname.com/api/callback&client_id=YOUR_CONSUMER_ID&client_secret=YOUR_CONSUMER_SECRET&code=aWekysIEeqM9PiThEfm0Cnr6MoLIfwWyRJcqOqHdF8f9INokharAS09ia7UNP6RiVScerfhc4w%3D%3D

Пример ответа:

{ "access_token": "YOUR_ACCESS_TOKEN", "refresh_token": "YOUR_REFRESH_TOKEN", "signature": "signature", "scope": "refresh_token api id", "instance_url": "https://instance.salesforce.com", "id": "https://login.salesforce.com/id/id, "token_type": "Bearer", "issued_at": "timestamp" }

Помимо токена доступа и ответа, instance_url также импортируется. Это то, что вам нужно для создания базы ваших будущих вызовов API.

Теперь у нас есть токен доступа, и мы можем начать делать запросы на отправку и получение данных от имени наших пользователей. Однако следует помнить, как упоминалось ранее, что срок действия этих токенов доступа всегда истекает в какой-то момент.

В связи с этим вам необходимо обновлять свой токен доступа, выполнив вызов конечной точки токена и изменив параметр grant_type на «refresh_token», а также включив токен обновления, который вы получили в предыдущий звонок.

Пример вызова:

curl https://login.salesforce.com/services/oauth2/token?grant_type=refresh_token&client_id=YOUR_CONSUMER__ID&client_secret=YOUR_CONSUMER__SECRET&refresh_token=YOUR_REFRESH_TOKEN

Пример ответа:

{ "access_token": "REFRESHED_ACCESS_TOKEN", "signature": "signature", "scope": "refresh_token id api", "instance_url": "https://INSTANCE.salesforce.com", "id": "https://login.salesforce.com/id/idE", "token_type": "Bearer", "issued_at": "timestamp" }

Теперь у нас есть способ сохранить наши токены доступа действительными и актуальными, мы настроены и готовы начать работу с объектами Salesforce.

Общие сведения об объектах Salesforce

объекты Salesforce (объекты) фактически представляют собой таблицы базы данных, содержащие данные организации. Примерами стандартных объектов Salesforce могут быть «Организации», «Контакты», «Интерес» и «Задачи». У вас также есть возможность создавать свои собственные настраиваемые объекты.

Запись Salesforce описывает конкретное вхождение объекта (например, конкретный контакт, такой как «Джонни Эпплсид», представленный объектом «Контакт»). Базовое сравнение будет похоже на строку в таблице базы данных.

В следующих примерах мы просто сосредоточимся на контактах.

Отправка данных из вашего приложения в Salesforce

Создать контакт в отделе продаж очень просто. Вам просто нужно создать URL-адрес API, используя экземпляр из ответа вашего токена доступа, и использовать значение токена доступа в качестве токена-носителя в заголовке.

Одна вещь, на которую следует обратить внимание, — это символы, которые необходимо экранировать в вашем токене доступа.

Например, этот токен доступа должен иметь экранированный восклицательный знак.

Итак, это:

00D1r000000dumU!AQEAQFd.O1Q5DVQrUYvr.........

Становится так:

00D1r000000dumU\!AQEAQFd.O1Q5DVQrUYvr........

затем вы можете сделать приведенный ниже вызов, чтобы создать контакт.

Пример запроса

curl https://INSTANCE.salesforce.com/services/data/v42.0/sobjects/Contact -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" -d '{"FirstName" : "Johnny", "LastName" : "Appleseed"}'

(Вашему контакту потребуется фамилия как минимум для создания записи.)

Ответ, который вы получите, будет идентификатором вашего контакта.

{"id":"0031r000029NDckAAG","success":true,"errors":[]}

Что также позволит вам создать ссылку непосредственно на контакт.

https://INSTANCE.salesforce.com/0031r000029NDckAAG

Получение данных из Salesforce в ваше приложение

Если вы хотите получить список контактов, это можно сделать несколькими способами. Вы можете сделать запрос к конечной точке контакта, и он вернет кучу информации о ваших контактах, которую я нашел немного громоздкой для навигации.

На самом деле я предпочитаю использовать комбинацию конечной точки «описания» контактов, которая вернет все поля, которые мы можем заполнить о нашем пользователе.

Пример запроса:

curl https://INSTANCE.salesforce.com/services/data/v20.0/sobjects/Contact/describe -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Это даст подробный ответ по всем доступным полям. (Я только что привел пример элемента «имя» для краткости)

{ "autoNumber": false, "byteLength": 120, "calculated": false, "calculatedFormula": null, "caseSensitive": false, "controllerName": null, "createable": true, "custom": false, "defaultValue": null, "defaultValueFormula": null, "defaultedOnCreate": false, "dependentPicklist": false, "deprecatedAndHidden": false, "digits": 0, "externalId": false, "filterable": true, "groupable": true, "htmlFormatted": false, "idLookup": false, "inlineHelpText": null, "label": "First Name", "length": 40, "name": "FirstName", "nameField": false, "namePointing": false, "nillable": true, "picklistValues": [], "precision": 0, "referenceTo": [], "relationshipName": null, "relationshipOrder": null, "restrictedPicklist": false, "scale": 0, "soapType": "xsd:string", "sortable": true, "type": "string", "unique": false, "updateable": true, "writeRequiresMasterRead": false }

Получив поля, вы можете использовать их (или выборку) для создания пользовательского запроса:

curl https://INstance.salesforce.com/services/data/v42.0/query/?q=SELECT+id,name,email,phone+from+Contact -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Это вернет все контакты со связанными с ними свойствами.

{"totalSize":1,"done":true,"records":[{"attributes":{"type":"Contact","url":"/services/data/v42.0/sobjects/Contact/id"},"Id":"id","Name":"Jonny Appleseed","Email":"[email protected]","Phone":"555-555-555"} ]}

Теперь это должно дать вам возможность получать контактные данные из Salesforce для использования в вашем приложении.

Дополнительные ресурсы

Надеемся, что это дает достаточно хорошую основу для изучения большего количества объектов Salesforce, с которыми вы можете взаимодействовать посредством интеграции REST API. Вот некоторые дополнительные ресурсы для получения более подробной информации о конечных точках Salesforce REST.

Первоначально опубликовано на сайте engineering.gosquared.com 6 июня 2018 г.