Node JS-SDK für Zoho CRM
Inhaltsverzeichnis
Node-SDK ist ein Wrapper für Zoho CRM-APIs. Deshalb ist der Aufruf einer Zoho CRM-API über Ihre Knotenanwendung nur ein Funktionsaufruf, der eine geeignete Reaktion aufruft.
Dieses SDK unterstützt die Authentifizierung eines oder mehrerer Benutzer.
Zoho-Client registrieren
Da die Zoho CRM-APIs mit OAuth2-Standards authentifiziert werden, sollten Sie Ihre Client-Anwendung mit Zoho registrieren. So registrieren Sie Ihre App:
- Besuchen Sie diese Seite https://accounts.zoho.com/developerconsole.
- Klicken Sie auf Client-ID hinzufügen.
- Geben Sie den Client-Namen, die Client-Domäne und die Weiterleitungs-URL ein.
- Wählen Sie den Client-Typ Webbasiert aus.
- Klicken Sie auf Erstellen.
- Ihre Client-App würde jetzt erstellt und angezeigt werden.
- Die neu registrierten Elemente "Client-ID" und "Vertrauliche Client-Daten" der Anwendung können durch Klicken auf "Optionen" → "Bearbeiten" gefunden werden.
(Optionen ist das Drei-Punkt-Symbol in der rechten Ecke).
Installation von Node-CRM-SDK
Node JS-SDK wird installiert und ein Paket mit dem Namen zcrmsdk wird auf dem lokalen Computer erstellt.
Das Paket kann mit dem folgenden Code hinzugefügt werden:
var ZCRMRestClient = require('zcrmsdk')
Installation von SDK
Hier erfahren Sie, wie Sie Node JS-SDK installieren
- Führen Sie den folgenden Befehl aus:
npm install zcrmsdk
Eine andere Methode, um das SDK zu installieren, ist, Abhängigkeiten der Datei package.json des Node-Servers mit der neuesten Version (empfohlen) hinzuzufügen und npm im Verzeichnis auszuführen, um alle in package.json genannten Abhängigkeiten zu installieren.
Upgrade des SDK
- Führen Sie diesen Befehl aus, um das Node JS-SDK auf die neueste Version zu aktualisieren.
npm install --upgrade zcrmsdk
Konfigurationen
Ihre OAuth-Client-Details sollten dem SDK als Eigenschaftsdatei angegeben werden. Im SDK müssen Sie eine Datei namens oauth_configuration.properties konfigurieren. Speichern Sie die entsprechenden Werte in dieser Datei ab. Sie können diese im Ordner Ressourcen speichern, aus dem das SDK stammt.
Geben Sie nur die Werte für die folgenden Schlüssel an.
Ändern Sie basierend auf Ihrer Domäne (EU, CN) den Wert von CRM. iamurl. Standardmäßig entspricht dieser der Domäne US.
In der Datei oauth_configuration.properties:
[zoho]
crm.iamurl=
crm.clientid=
crm.clientsecret=
crm.redirecturl=
- crm.clientid, crm.clientsecret und crm.redirecturl sind die Konfigurationen Ihres OAuth-Clients, die Sie nach dem Registrieren Ihres Zoho-Clients erhalten.
- crm. iamurl ist die URL des Kontos. Diese kann accounts.zoho.com oder accounts.zoho.eu entsprechen. Wenn crm.iamurl nicht angegeben wird, entspricht die URL standardmäßig accounts.zoho.com.
In der Datei configuration.properties:
[crm]
api.url=
api.user_identifier=
api.tokenmanagement=
[mysql]
username=
password=
- api.-url ist die URL, die wird verwendet, um APIs aufzurufen. Standardmäßig entspricht die URL www.zohoapis.com.
- Api.user_id ist standardmäßig leer. Für die Authentifizierung einzelner Benutzer kann die jeweilige E-Mail-ID für diesen Schlüssel verwendet werden, sodass alle Aufrufe durch die Authentifizierung des Benutzers geschehen.
- api.tokenmanagement dient der Verwaltung und Pflege von Token. Wenn tokenmanagement nicht angegeben wird, dann wird standardmäßig implementation(mysql) befolgt.
- Benutzername und Kennwort können hier angegeben werden, wenn Sie diese Angaben bereits für MySQL erstellt haben.
Alle oben genannten Schlüssel der Datei configuration.properties sind optional.
Token-Speichermechanismus
Gehen Sie wie folgt vor, um den vom SDK bereitgestellten Token-Speichermechanismus zu verwenden:
Mysql sollte im Standard-Port in Localhost ausgeführt werden.
Die Datenbank mit dem Namen zohooauth muss erstellt werden und eine Tabelle mit folgenden Konfigurationen sollte in der Datenbank vorhanden sein. Tabelle mit dem Namen oauthtokens, mit den Spalten useridentifier (varchar), accesstoken (varchar), refreshtoken (varchar) und expirytime (bigint).
Sobald die Konfiguration eingestellt wurde, werden die Speicherung und der Abruf von Tokens vom SDK behandelt.
Wenn der Benutzer seinen eigenen Mechanismus nutzen möchte, kann er dies in configuration.properties erwähnen, indem er das jeweilige Modul api.tokenmanagement bereitstellt.
Dieses Modul sollte die folgenden Methoden enthalten:
- saveOAuthTokens(token_obj)
- updateOAuthTokens(token_obj)
- Unabhängig von der Antwort folgt die nächste Ausführung. Daher muss der Benutzer sehr vorsichtig mit den Modulen vorgehen.
- getOAuthTokens()
- Die erwartete Antwort für diese Methode lautet JSON-Array und enthält die JSON-Antwort mit den Feldern expirytime, refreshtoken und accesstoken.
Hinweis:
- Alle Methoden sollten promise zurückgeben.
saveOAuthtoken & updateOAuthTokens wird mit den JSON-Parametern aufgerufen, die die unten angegebenen Felder enthalten:
access_token
refresh_token
expires_in
Beispielcode für benutzerdefiniertes Token-Management getOAuthTokens ()
tokenmanagement.getOAuthTokens = function(user_identifier){ //expires in : 1527839622728
return new Promise(function(resolve,reject){
var result = {};
result.accesstoken = '1000.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx';
result.expirytime = 15278396227289
result.refreshtoken = '1000.xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxx';
var result_array =[];
result_array.push(result);
resolve(result_array);
});
}
Initialisierung
Wenn die Anwendung gestartet wird, wird der folgende Codeausschnitt für die Initialisierung aufgerufen.
var ZCRMRestClient = require('zcrmsdk');
ZCRMRestClient.initialize().then(function()
{
//do whatever required after initialize
})
Selbstautorisierten Gewährungs- und Aktualisierungs-Token erzeugen
Für die Client-Apps sollten die selbstautorisierten Gewährungs-Token über die Zoho-Entwicklerkonsole erzeugt werden (https://accounts.zoho.com/developerconsole)
- Besuchen Sie https://accounts.zoho.com/developerconsole
- Klicken Sie auf Optionen → Eigener Client des Clients, für den die Autorisierung durchgeführt werden soll.
- Geben Sie im Feld Bereich einen oder mehrere (durch Komma getrennte) gültige Zoho CRM-Bereiche an, die Sie autorisieren möchten. Wählen Sie dann die Ablaufzeit. Geben Sie den Bereich aaaserver.profile.READ mit den Zoho CRM-Bereichen an.
- Kopieren Sie das Gewährungs-Token für das Backup.
- Generieren Sie refresh_token über das Gewährungs-Token, indem Sie eine POST-Anforderung über die untere URL erstellen
https://accounts.zoho.com/oauth/v2/token?code={grant_token}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&grant_type=authorization_code
- Kopieren Sie das Aktualisierungs-Token für das Backup.
Wir weisen Sie darauf hin, dass das erzeuge Gewährungs-Token nur für die beim Erzeugen definierte Dauer gilt. Daher müssen das Zugriffs- und Aktualisierungs-Token innerhalb dieses Zeitraums erzeugt werden.
Bei jedem Neustart des Servers muss diese Funktion aufgerufen werden und die Konfigurationsdateien sollten mit den geeigneten Werten ausgefüllt werden, bevor diese Funktion aufgerufen wird, um Ausnahmen zu vermeiden.
Alle Funktionen geben Promises in zcrm node sdk zurück.
Zugriffs- und Aktualisierungs-Token über die Methodenaufrufe der Gewährungs-Token abrufen
ZCRMRestClient.generateAuthTokens(user_identifier,grant_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});
Die Zugriffs- und Aktualisierungs-Token werden generiert. Für den Fall, dass das Zugriffs-Token abgelaufen ist, wird das SDK automatisch aktualisiert.
Wenn der Benutzer über Aktualisierungs-Token verfügt und Zugriffs-Token erzeugen muss, kann die folgende Funktion verwendet werden:
ZCRMRestClient.generateAuthTokenfromRefreshToken(user_identifier,refresh_token).then(function(auth_response){
console.log("access token :"+auth_response.access_token);
console.log("refresh token :"+auth_response.refresh_token);
console.log("expires in :"+auth_response.expires_in);
});
Beispiel-API-Aufruf für Leads:
var input ={};
input.module = "Leads";
var params = {};
params.page = 0;
params.per_page = 5;
input.params = params;
zcrmsdk.API.MODULES.get(input).then(function(response){
var result = "<html><body><b>Leads</b>";
var data = response.body;
data = JSON.parse(data);
data = data.data;
for (i in data){
var record = data[i];
var name = record.Full_Name;
result+="<span>"+name+"</span>";
}
result+="</body></html>";
})
Hierarchie
zcrmsdk
API
ORG
get
MODULES
get
post
put
delete
getAllDeletedRecords
getRecycleBinRecords
getPermanentlyDeletedRecords
search
SETTINGS
getFields
getLayouts
getCustomViews
updateCustomViews
getModules
getRoles
getProfiles
getRelatedLists
ACTIONS
convert
USERS
get
ATTACHMENTS
uploadFile
deleteFile
downloadFile
uploadLink
uploadPhoto
downloadPhoto
deletePhoto
FUNCTIONS
executeFunctionsInGet
executeFunctionsInPost
Wie es in der Hierarchie erscheint, verfügt das Entitätenmodul zcrmsdk über eigene Variablen, um seine eigenen Eigenschaften und die anderer Module abzurufen.
Zum Beispiel sollte die Anforderung für einen API-Aufruf, um Moduldaten zu erhalten, wie folgt lauten: zcrmsdk.API.MODULES.{operation_type}. Die Vorgangstypen können GET, POST, PUT, DELETE oder CREATE entsprechen.
Handhabung von Antworten
Alle API-Aufrufe geben die eigentliche API-Antwort der Zoho-APIs zurück, außer "Datei herunterladen".
Für die Antwort "Datei herunterladen" enthält die Reaktion ein zusätzliches Feld "Dateiname".
Fehlerbehandlung:
Alle Fehler werden explizit ausgelöst und sollten sorgfältig behoben werden.