PHP-SDK für Zoho CRM

PHP-SKD ist ein Wrapper für Zoho CRM-APIs. Deshalb ist der Aufruf einer Zoho CRM-API von Ihrer PHP-Client-Anwendung nur ein Funktionsaufruf. Er 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:

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

PHP-SDK kann mit Composer installiert werden. Composer ist ein Werkzeug für die Verwaltung von Abhängigkeiten in PHP. SDK erwartet Folgendes von der Client-App:

• Die Client-App muss über PHP 5.6 oder höher mit curl-Erweiterung verfügen.
• PHP-SDK muss in der Client-App mit Composer installiert werden.
• Die Funktion ZCRMRestClient::initialize() muss beim Start der 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 "useridentifier" (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.txt im erwähnten token_persistence_path.

Installation von PHP-SDK mit Composer

Composer installieren (falls nicht installiert)

Installieren Sie Composer über diesen Befehl

Der Composer ist weltweit zugänglich, folgen Sie den Anweisungen des nachstehenden Links

PHP-SDK installieren

Hier erfahren Sie, wie Sie das SDK installieren

1. Navigieren Sie zu dem Arbeitsbereich Ihrer Client-App
2. Führen Sie den folgenden Befehl aus:

   composer require zohocrm/php-sdk-archive

3. Daher würde das PHP-SDK installiert und ein Paket namens Anbieter im Arbeitsbereich Ihrer Client-App erstellt werden.

Konfigurationen

Ihre OAuth-Client-Details sollten dem PHP-SDK als Eigenschaftsdatei angegeben werden. In PHP-SDK befindet sich eine Konfigurationsdatei (oauth_configuration.properties). Speichern Sie die entsprechenden Werte in dieser Datei ab. Sie können diese Datei unter vendor/zohocrm/php-sdk/src/resources finden.

Geben Sie nur 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.

• Nur die oben angezeigten Schlüssel müssen angegeben werden.
• 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 Einstellung "online OAuth Client" nicht vom PHP-SDK unterstützt wird.
• persistence_handler_class ist die Implementierung von ZohoOAuthPersistenceInterface, d.h. ZohoOAuthPersistenceHandler.
• token_persistence_path entspricht dem Speicherpfad der entsprechenden Token-Datei von OAuth. Wurde dies eingestellt, ist keine Datenbank für Persistenz nötig. Die Persistenz geschieht nur durch die Datei.

Erstellen Sie eine Datei mit dem Namen "ZCRMClientLibrary.log" auf Ihrem Computer der Client-App und nennen Sie den absoluten Pfad der erstellten Datei in configuration.properties für den Schlüssel "applicationLogFilePath". Sie können diese Datei unter vendor/zohocrm/php-sdk/src/resources finden. Diese Datei protokolliert die Ausnahmen, die bei der Verwendung von PHP-SDK aufgetreten sind.

Geben Sie nur die folgenden Schlüssel an

Um API-Aufrufe mit dem Sandbox-Konto zu machen, ändern Sie den Wert der folgenden Schlüssel auf true in der Datei configurations.properties . 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 superglobale Variable '$_SERVER" der Benutzer-Email-ID in PHP wie unten angegeben einstellen:

Sie können die Variable $_SERVER für die 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 als superglobale Variable festlegen, dann erwartet SDK dies in der Datei configuration.properties. Wenn die Benutzer-E-Mail in keiner dieser beiden Dateien eingestellt wird, dann gibt PHP-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- und Gewährungs-Token generieren

Der folgende Codeausschnitt sollte von Ihrer Hauptklasse ausgeführt werden, um Zugriffs- und Aktualisierungs-Token zu generieren. Fügen Sie das kopierte Gewährungs-Token in den ausdrücklich nachstehend genannten String ein. Dies ist ein einmaliger Vorgang.

Beachten Sie, dass der obige Codeausschnitt nur einmal pro Gewährungs-Token gültig ist. Nach der erfolgreichen Ausführung des obigen Codeausschnitts blieben die erzeugten Zugriffs- und Aktualisierungs-Token durch ihre Persistenz-Handler-Klasse erhalten.

Zugriffs-Token über Aktualisierungs-Token generieren

Der folgende Codeausschnitt sollte von Ihrer Hauptklasse ausgeführt werden, um Zugriffs- und Aktualisierungs-Token zu generieren. Fügen Sie das generierte Aktualisierungs-Token in den ausdrücklich nachstehend genannten String ein. Dies ist ein einmaliger Vorgang.

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 PHP-SDK sorgt für die Aktualisierung des Zugriffs-Tokens mithilfe des Aktualisierungs-Token, sofern und wenn erforderlich.

App starten

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

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

Mit PHP-SDK

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

Durch diese Zeile erhalten Sie Zugriff auf alle Funktionalitäten des PHP-SDK.

Klassenhierarchie

Alle Zoho CRM-Einheiten werden als Klassen mit Eigenschaften und Funktionen modelliert, die sich auf diese bestimmte Entität anwenden lassen. ZCRMRestClient ist die Basisklasse des PHP-SDK. ZCRMRestClient weist Funktionen zum Abrufen von Instanzen verschiedener anderer Zoho CRM-Entitäten auf.

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:

ZCRMRestClient
     -ZCRMOrganization
          -ZCRMUser
               -ZCRMUserTheme
               -ZCRMUserCustomizeInfo
         -ZCRMRole
         -ZCRMProfile
              -ZCRMPermission
              -ZCRMProfileSection
                   -ZCRMProfileCategory
        -ZCRMModule
             -ZCRMLayout
                  -ZCRMSection
                       -ZCRMField
                       -ZCRMPickListValue
                       -ZCRMLookupField
                  -ZCRMLeadConvertMapping
                       -ZCRMLeadConvertMappingField
             -ZCRMCustomView
                  -ZCRMCustomViewCategory
                  -ZCRMCustomViewCriteria
             -ZCRMRelatedListProperties
                  -ZCRMModuleRelatedList
             -ZCRMRecord
             -ZCRMNote
             -ZCRMAttachment
             -ZCRMInventoryLineItem
                  -ZCRMTax
             -ZCRMEventParticipant
             -ZCRMPriceBookPricing
             -ZCRMModuleRelation
             -ZCRMJunctionRecord
             -ZCRMTrashRecord

Jede Entitätenklasse verfügt über Funktionen zum Abrufen der eigenen Eigenschaften und zum Abrufen der Daten direkt untergeordneter Entitäten durch einen API-Aufruf.

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

Instanzobjekt

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 Funktion getInstance(), um ein eigenes Dummy-Objekt abzurufen. Außerdem sind Funktionen zum Abrufen von Dummy-Objekten untergeordneter Entitäten vorhanden.

Wir weisen Sie darauf hin, dass getInstance()-Funktionen nicht zum Ausfüllen dieser Eigenschaften führen, 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 Funktionen einer Klasse verwendet wird.

Zusammenfassung:

• ZCRMRestClient::getModule("Contacts") würde das eigentliche Kontaktmodul zurückgeben, das über alle Eigenschaften des Kontaktmoduls verfügt, die über einen API-Aufruf eingetragen werden.
• ZCRMRestClient::getModuleInstance("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 die Datensätze aus einem Modul abzurufen, muss nicht mit ZCRMRestClient begonnen werden. Stattdessen können Sie eine Instanz von ZCRMModule mit ZCRMModule::getInstance() abrufen und dann die nicht statische Funktion getRecords() 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 Felder wie "createdTime", "createdBy", "owner" usw. als Standardeigenschaften von ZCRMRecord festgelegt. Alle anderen Datensatzeigenschaften stehen als Übersicht im Objekt ZCRMRecord zur Verfügung.

Für den Zugriff auf die einzelnen Feldwerte eines Datensatzes verwenden Sie die verfügbaren Getter- und Setter-Funktionen. Die Schlüssel der Übersicht zu den Datensatzeigenschaften sind die API-Namen der Modulfelder. Alle API-Namen aller Module finden sich unter Setup → Marketplace → APIs → CRM-API → API-Namen.

• Um einen Feldwert zu erhalten, benutzen Sie $record → getFieldValue($fieldAPIName);
• Um einen Feldwert festzulegen, benutzen Sie $record → setFieldValue($fieldAPIName, $newValue);
  Stellen Sie beim Festlegen eines Feldwerts sicher, dass der eingestellte Wert dem Datentyp des betreffenden Felds entspricht.

Handhabung von Antworten

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

• DownloadFile und downloadPhoto geben FileAPIResponse anstelle von APIResponse zurück.
• Eine Funktion zur Suche einer einzelnen Entität gibt APIResponse zurück, während eine Methode zur Suche einer Entitätenliste ein BulkAPIResponse-Objekt zurückgibt.
• Verwenden Sie die Funktion getData(), um nur die Entitätendaten aus dem Antwort-Wrapper-Objekt abzurufen. APIResponse → getData() würde ein einzelnes Zoho CRM-Entitätsobjekt zurückgeben, während BulkAPIResponse → getData() eine Liste von Zoho CRM-Entitätsobjekten zurückgeben würde.

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

1. ResponseHeaders – Die verbleibende API ermittelt den aktuellen Tag/das Fenster und die verstrichene Zeit für das Zurücksetzen des aktuellen Fensters.
2. ResponseInfo – Alle anderen Informationen, sofern neben den eigentlichen Daten von der API bereitgestellt.
3. Array mit EntityResponse(s) – 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 PHP-SDK gehandhabt und nur in Form einer einzigen Ausnahme ausgegeben – ZCRMException. Daher reicht es aus, nur diese Ausnahme im Code der Client-App abzufangen.