Python-SDK für Zoho CRM-APIs bietet Wrapper für Zoho CRM-APIs. Deshalb ist der Aufruf einer Zoho CRM-API von Ihrer Python-Client-Anwendung nur ein Methodenabruf.

Python-SDK unterstützt die Authentifizierung einzelner und 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:

1. Besuchen Sie diese Seite https://accounts.zoho.com/developerconsole.
2. Klicken Sie auf Client-ID hinzufügen.
3. Geben Sie den Client-Namen, die Client-Domäne und die Weiterleitungs-URL ein.
4. Wählen Sie den Client-Typ Webbasiert aus.
5. Klicken Sie auf Erstellen.
6. Ihre Client-App würde jetzt erstellt und angezeigt werden.
7. 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).

Einrichtung

Python-SDK ist mit "Pip" installierbar. Pip ist ein Werkzeug für die Verwaltung von Abhängigkeiten in Python. Das SDK erwartet Folgendes von der Client-App

• Die Client-App muss über Python 2.7 und höher verfügen.
  • https://www.python.org/downloads/
• Die Client-App muss über installierte Python-Anforderungen verfügen.
  • http://docs.python-requests.org/en/master/user/install/
• Python-SDK muss mit Pip installiert werden.
• Die Methode ZCRMRestClient.initialize() muss beim Starten Ihrer Anwendung aufgerufen werden
• MySQL sollte auf derselben Maschine auf dem Standard-Port 3306 laufen.
  • Der Datenbankname muss zohooauth lauten.
  • Es muss eine Tabelle "oauthtokens" mit den Spalten "user identifier" (varchar(100)), "accesstoken" (varchar(100)), "refreshtoken" (varchar(100)), "expirytime" (Bigint) vorhanden sein.

Wenn token_persistence_path in der Datei oauth_configuration.properties angegeben wird, geschieht die Persistenz nur in der Datei. In diesem Fall ist MySQL nicht nötig.

Erstellen Sie eine leere Datei mit dem Namen

zcrm_oauthtokens.pkl im erwähnten token_persistence_path.

Installation von SDK über Pip

Pip installieren (falls nicht installiert)

Lesen Sie das nachstehende Dokument, um Pip zu installieren

Installieren Sie SDK

Hier erfahren Sie, wie Sie Python-SDK installieren

• Führen Sie den folgenden Befehl aus:

  pip install zcrmsdk

Python-SDK wird installiert und ein Paket mit dem Namen 'zcrmsdk' wird im Installationsverzeichnis von Python erstellt (z. B.: '/Library/Python/2.7/site-packages').

Upgrade des SDK

• Führen Sie diesen Befehl aus, um Python-SDK auf die neueste Version zu aktualisieren.

  pip install --upgrade zcrmsdk

Konfigurationen

Ihre OAuth-Client-Details sollten dem SDK als Eigenschaftsdatei angegeben werden. Im SDK befindet sich eine Konfigurationsdatei (oauth_configuration.properties). Speichern Sie die entsprechenden Werte in dieser Datei ab. Sie können diese Datei unter 'zcrmsdk/resources' finden.

Geben Sie nur die Werte für die folgenden Schlüssel an.

Ändern Sie basierend auf Ihrer Domäne (EU, CN) den Wert von accounts_url. Standardmäßig entspricht dieser der Domäne US.

• client_id, client_secret und redirect_uri sind die Konfigurationen Ihres OAuth-Clients, die Sie nach dem Registrieren Ihres Zoho-Clients erhalten.
• access_type muss auf offline gesetzt werden, da die Online-Einstellung des OAuth-Client nicht vom Python-SDK unterstützt wird.
• token_persistence_path entspricht dem Speicherpfad der entsprechenden Token-Datei von OAuth. Wurde dies eingestellt, ist keine Datenbank für die Persistenz mehr nötig. Die Persistenz geschieht nur durch die Datei.

Schließen Sie den absoluten Pfad in configuration.properties für den Schlüssel "applicationLogFilePath" für die Speicherung der Protokolle ein. Sie können diese Datei unter zcrmsdk/resources finden. Diese Datei protokolliert die Ausnahmen, die bei der Verwendung von Pyhton-SDK aufgetreten sind.

Geben Sie nur den Wert für den folgenden Schlüssel an. Wenn der Protokollpfad nicht vorhanden ist, werden die Protokolle nicht gespeichert, können aber in der Konsole angezeigt werden

Um API-Aufrufe mit dem Sandbox-Konto zu machen, ändern Sie bitte den Wert der folgenden Schlüssel auf "true". Standardmäßig ist der Wert false.

Wenn Ihre Anwendung nur die Authentifizierung einzelner Benutzer benötigt, dann müssen Sie die Benutzer-Email-ID in der Datei "configurations.properties" wie unten angegeben einstellen.

Um mit der Authentifizierung mehrerer Benutzer zu arbeiten, müssen Sie die Benutzer-Email-ID im aktuellen Thread als Attribut einstellen:

Sie können auch die obere Authentifizierung einzelner Benutzer verwenden, es wird jedoch empfohlen, die E-Mail-ID in der Datei configuration.properties einzustellen.

Wenn Sie die Benutzer-E-Mails nicht im aktuellen Thread einstellen, dann erwartet SDK diese in der Datei configuration.properties. Wenn die Benutzer-E-Mail in keiner dieser beiden Dateien eingestellt wird, dann gibt Python-SDK eine Ausnahme aus.

Initialisierung

Die App wäre nach der Definition der OAuth-Konfigurationsdatei für die Initialisierung bereit.

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)

1. Besuchen Sie https://accounts.zoho.com/developerconsole
2. Klicken Sie auf Optionen → Eigener Client des Clients, für den die Autorisierung durchgeführt werden soll.
3. 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.
4. Kopieren Sie das Gewährungs-Token für das Backup.
5. 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

6. 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.

Zugriffs-Token generieren

Zugriffs-Token können durch Gewährungs-Token oder Aktualisierungs-Token generiert werden. Die Befolgung einer der beiden Methoden ist ausreichend.

Zugriffs- über Gewährungs-Token generieren

Der folgende Codeausschnitt sollte von Ihrer Hauptklasse ausgeführt werden, um Zugriffs-Token zu generieren.

Fügen Sie das generierte Gewährungs-Token in den ausdrücklich genannten String ein.

Hierbei handelt es sich um einen einmaligen Prozess.

Zugriffs- und Aktualisierungs-Token generieren

Der folgende Codeausschnitt sollte von Ihrer Hauptklasse ausgeführt werden, um Zugriffs-Token zu generieren.

Fügen Sie das generierte Aktualisierungs-Token in den ausdrücklich genannten String ein.

Hierbei handelt es sich um einen einmaligen Prozess.

Nach der erfolgreichen Ausführung des obigen Codeausschnitts blieben die erzeugten Zugriffs- und Aktualisierungs-Token durch ihre Persistenz-Handler-Klasse erhalten.

Sobald die OAuth-Token gespeichert sind, verwenden die folgenden API-Aufrufe die persistierenden Zugriffs- und Aktualisierungs-Token. Das Python-SDK sorgt für die Aktualisierung des Zugriffs-Tokens mithilfe des Aktualisierungs-Tokens, sofern und wenn erforderlich.

App starten

Das Python-SDK erfordert den Aufruf der folgenden Codezeile bei jedem Starten Ihrer Client-App.

Sobald das SDK durch die Zeile oben initialisiert wurde, könnten Sie jede API des SDK verwenden, um korrekte Ergebnisse zu erhalten.

Mit SDK

Fügen Sie die folgende Zeile in die Python-Dateien Ihrer Client-App ein, in der Sie Python-SDK verwenden möchten.

Somit erhalten Sie Zugriff auf alle Funktionalitäten des Python-SDK.

Klassenhierarchie

Alle Zoho CRM-Entitäten werden als Module mit Klassen-, Methoden- und Instanzvariablen modelliert, die sich auf diese bestimmte Entität anwenden lassen. ZCRMRestClient ist die Basisklasse des Python-SDK. ZCRMRestClient weist Methoden zum Abrufen von Instanzen verschiedener anderer Zoho CRM-Entitäten auf. Es ist in RestClient-Modul.

Die Beziehungen zwischen den Klassen und die Klassenhierarchie des SDK folgen der Entitätenhierarchie innerhalb von Zoho CRM. Die Klassenhierarchie der verschiedenen Zoho CRM-Entitäten ist unten angegeben:

Wie in der Hierarchie gezeigt, verfügt jede Entitätenklasse über Instanzvariablen zum Abruf der eigenen Eigenschaften und der Daten direkt untergeordneter Entitäten über einen API-Aufruf.

Beispiel: Ein Zoho CRM-Modulobjekt (ZCRMModule) verfügt über Instanzvariablen zum Abrufen von Moduleigenschaften, wie Anzeigename, Modul-ID usw., sowie über Instanzvariablen zum Abrufen aller untergeordneten Objekte (etwa ZCRMLayout).

Objekte instanziieren

Es ist nicht immer effektiv, der gesamten Klassenhierarchie von oben nach unten zu folgen, um die Daten einer Entität auf einer unteren Ebene abzurufen, da dies zu API-Aufrufen auf jeder Ebene führen würde. Um dies zu vermeiden, verfügt jede Entitätenklasse über die Methode get_instance(), um ein eigenes Dummy-Objekt abzurufen. Außerdem sind Instanzvariablen zum Abrufen von Dummy-Objekten untergeordneter Entitäten vorhanden.

Wir weisen Sie darauf hin, dass die get_instance()-Methode nicht zum Ausfüllen dieser Eigenschaften führt, da kein API-Aufruf ausgelöst wird. Dies würde nur ein Dummy-Objekt zurückgeben, das nur für den Zugriff auf die nicht statischen Methoden einer Klasse verwendet wird.

Zusammenfassung:

• ZCRMRestClient.get_module("Contacts") würde das eigentliche Kontaktmodul zurückgeben, das über alle Eigenschaften des Kontaktmoduls verfügt, die über einen API-Aufruf eingetragen werden.
• ZCRMRestClient.get_module_instance("Contacts") würde ein ZCRMModule-Dummy-Objekt zurückgeben, das sich auf das Kontaktmodul bezieht. Die Eigenschaften wären nicht ausgefüllt, da kein API-Aufruf erfolgt.

Um Datensätze aus einem Modul zu erhalten, müssen Sie nicht erneut mit ZCRMRestClient beginnen. Stattdessen können Sie eine Instanz von ZCRMModule mit ZCRMModule.get_instance() abrufen und dann die nicht statische Methode get_records() der erstellten Instanz aufrufen. Dies würde den API-Aufruf vermeiden, der ausgelöst worden wäre, um das Objekt ZCRMModule auszufüllen.

Zugriff auf Datensatzeigenschaften

Da Datensatzeigenschaften modulübergreifend dynamisch sind, wurden nur die allgemeinen Felder wie created_time, created_by, owner usw. als Standardeigenschaften von ZCRMRecord festgelegt. Alle anderen Datensatzeigenschaften stehen als Wörterbuch im Objekt ZCRMRecord zur Verfügung.

Für den Zugriff auf die einzelnen Feldwerte eines Datensatzes verwenden Sie die verfügbaren Getter- und Setter-Methoden. Die Schlüssel des Wörterbuchs zu den Datensatzeigenschaften sind die API-Namen der Modulfelder. API-Namen aller Felder für alle Module finden sich unter Setup → Erweiterung & APIs → APIs → CRM-API → API-Namen.

Zum Abrufen eines Feldwerts verwenden Sie record.get_field_value(field_api_name). Verwenden Sie zum Festlegen eines Feldwerts record.set_field_value(field_api_name,new_value). Stellen Sie beim Festlegen eines Feldwerts sicher, dass dieser Wert dem Datentyp des betreffenden Felds entspricht.

Handhabung von Antworten

APIResponse und BulkAPIResponse sind Wrapper-Objekte für Zoho CRM-API-Antworten. Alle API-Aufrufmethoden geben eines dieser beiden Objekte zurück.

DownloadFile und downloadPhoto geben FileAPIResponse anstelle von APIResponse zurück.

Eine Methode zur Suche einer einzelnen Entität gibt ein APIResponse-Objekt zurück, während eine Methode zur Suche einer Entitätenliste ein BulkAPIResponse-Objekt zurückgibt.

Verwenden Sie die Instanzvariable data, um nur die Entitätsdaten von den Antwort-Wrapper-Objekten herunterzuladen. APIResponse.data würde ein einzelnes Zoho CRM-Entitätsobjekt zurückgeben, während BulkAPIResponse.data eine Liste von Zoho CRM-Entitätsobjekten zurückgeben würde.

Neben den Daten weisen diese Antwort-Wrapper-Objekte folgende Eigenschaften auf:

1. response_headers – Die verbleibende API ermittelt den aktuellen Tag/das Fenster und die verstrichene Zeit für das Zurücksetzen des aktuellen Fensters.
2. info – Alle anderen Informationen, sofern neben den eigentlichen Daten von der API bereitgestellt.
3. bulk_entity_response (list of EntityResponse instances) – Status der einzelnen Entitäten in der Massen-API. Beispiel: Eine API zum Einfügen von Datensätzen kann aufgrund einiger Datensätze fehlschlagen. Dieses Array enthält den Erstellungsstatus der einzelnen Datensätze.

Ausnahmen

Unerwartetes Verhalten, darunter fehlerhafte API-Antworten und SDK-Anomalien, werden vom Python-SDK gehandhabt und nur in Form einer einzigen Ausnahme ausgelöst: ZCRMException. Daher reicht es aus, nur diese Ausnahme im Client-App-Code abzufangen.

Klassen und deren Instanzvariablen