Benutzerdefinierte Objekte

Sie können benutzerdefinierte Objekte mithilfe einer der folgenden Authentifizierungsmethoden erstellen, lesen und aktualisieren:

• OAuth
• Zugriffstoken von privaten Apps

Um ein benutzerdefiniertes Objekt zu erstellen, müssen Sie zunächst das Objektschema definieren. Das Schema enthält den Objektnamen, Eigenschaften und Zuordnungen zu anderen CRM-Objekten. Die vollständigen Schema-Anfragedetails finden Sie oben in diesem Artikel auf der Registerkarte „Objektschema“. Sie können sich auch eine Beispielanfrage in der Beispieldemonstration unten ansehen.

Um das benutzerdefinierte Objektschema zu erstellen, führen Sie eine POST-Anfrage an crm/v3/schemas durch. Fügen Sie im Anfragetext Definitionen für Ihr Objektschema ein, einschließlich Name, Eigenschaften und Zuordnungen.

Wenn Sie Ihr benutzerdefiniertes Objekt benennen, beachten Sie Folgendes:

• Sobald Sie ein Objekt erstellt haben, können der Name und das Label des Objekts nicht mehr geändert werden.
• Der Name darf nur Buchstaben, Ziffern, Unterstriche und Bindestriche enthalten.
• Das erste Zeichen des Namens muss ein Buchstabe sein.
• Lange Label können in bestimmten Teilen des Produkts abgeschnitten werden.

Im Folgenden finden Sie die erforderlichen Definitionen für die Eigenschaften und Zuordnungen des Objekts. 

Die Eigenschaften, die Sie im Anfragetext definieren, werden verwendet, um Informationen zu einzelnen benutzerdefinierten Objektdatensätzen zu speichern.

Sie verwenden Ihre definierten Eigenschaften, um die folgenden eigenschaftsbasierten Felder zu füllen:

• requiredProperties: Die Eigenschaften, die beim Erstellen eines neuen benutzerdefinierten Objektdatensatzes erforderlich sind.
• searchableProperties: Die Eigenschaften, die für die Suche in HubSpot indiziert werden.
• primaryDisplayProperty: Die Eigenschaft, die zum Benennen einzelner benutzerdefinierter Objektdatensätze verwendet wird.
• secondaryDisplayProperties: Die Eigenschaften, die in einzelnen Datensätzen unter der primären Anzeigeeigenschaft angezeigt werden.
  
  • Die erste Eigenschaft, die in secondaryDisplayProperties aufgeführt ist, wird auch als vierter Filter auf der Indexseite des Objekts hinzugefügt, wenn es sich um einen der folgenden Eigenschaftstypen handelt:
    • string
    • number
    • enumeration
    • boolean
    • datetime
      
  • Um eine Anzeigeeigenschaft von der Benutzeroberfläche zu entfernen, müssen Sie die Eigenschaft zunächst löschen und dann neu erstellen.

Beim Erstellen von Eigenschaften über die Schemaanfrage wird standardmäßig der type der Eigenschaft auf string und der fieldType auf text festgelegt. Unten sind die Werte, die Sie verwenden können, um verschiedene Typen von Eigenschaften zu erstellen.

Zuordnungen

HubSpot ordnet den E-Mails, Meetings, Notizen, Aufgaben, Anrufen und Konversationen automatisch ein benutzerdefiniertes Objekt zu. Sie können außerdem Ihr benutzerdefiniertes Objekt auch mit anderen Standard-HubSpot-Objekten oder anderen benutzerdefinierten Objekten verknüpfen.

Identifizieren Sie beim Erstellen von Zuordnungen über die Anfrage zum Erstellen eines Schemas Standardobjekte anhand ihres Namens und benutzerdefinierte Objekte anhand ihres objectTypeId-Werts. Zum Beispiel:

Um alle benutzerdefinierten Objekte abzurufen, führen Sie eine GET-Anfrage an /crm/v3/schemas durch.

Um ein bestimmtes benutzerdefiniertes Objekt abzurufen, führen Sie eine GET-Anfrage an einen der folgenden Endpunkte durch:

• /crm/v3/schemas/{objectTypeId}
• /crm/v3/schemas/p_{object_name}
• /crm/v3/schemas/{fullyQualifiedName}. Sie können den

  fullyQualifiedName eines Objekts in seinem Schema finden, das von p{portal_id}_{object_name} abgeleitet wird. Sie können die Portal-ID Ihres Accounts mithilfe der Account-Informationen-API finden.

Für einen Account mit der ID 1234 und ein Objekt mit dem Namen lender könnte Ihre Anfrage-URL beispielsweise wie folgt aussehen:

• https://api.hubapi.com/crm/v3/schemas/2-3465404
• https://api.hubapi.com/crm/v3/schemas/p_lender
• https://api.hubapi.com/crm/v3/schemas/p1234_lender

Um das Schema eines Objekts zu aktualisieren, führen Sie eine PATCH-Anfrage an https://api.hubapi.com/crm/v3/schemas/{objectTypeId} durch.

Sobald Ihr benutzerdefiniertes Objekt definiert ist:

• Der Name und das Label des Objekts (Singular und Plural) können nicht geändert werden.
• Die requiredProperties, searchableProperties, primaryDisplayProperty und secondaryDisplayProperties können durch Aktualisieren des Schemas des Objekts geändert werden. Um eine neue Eigenschaft als erforderlich, durchsuchbar oder Anzeigeeigenschaft festzulegen, müssen Sie die Eigenschaft vor dem Aktualisieren des Schemas erstellen.
• Sie können benutzerdefinierte Objekteigenschaften entweder in HubSpot oder über die Eigenschaften-API erstellen und bearbeiten. 

Zuordnungen aktualisieren

Um weitere Objektzuordnungen zu Ihrem benutzerdefinierten Objekt hinzuzufügen, führen Sie eine POST-Anfrage an/crm/v3/schemas/{objectTypeId}/associations durch.

Sie können Ihr benutzerdefiniertes Objekt nur Standard-HubSpot-Objekten (z. B. Kontakte, Unternehmen, Deals oder Tickets) oder anderen benutzerdefinierten Objekten zuordnen. Identifizieren Sie im toObjectTypeId-Feld benutzerdefinierte Objekte nach ihrem objectTypeId-Wert und Standardobjekte nach ihrem Namen. Beispiel:

Sie können ein benutzerdefiniertes Objekt nur löschen, nachdem alle Objektinstanzen von diesem Typ gelöscht wurden. Um ein benutzerdefiniertes Objekt zu löschen, führen Sie eine DELETE-Anfrage an /crm/v3/schemas/{objectType} durch.

Wenn Sie ein neues benutzerdefiniertes Objekt mit dem gleichen Namen wie das gelöschte Objekt erstellen müssen, müssen Sie das Schema dauerhaft löschen, indem Sie eine DELETE-Anfrage an /crm/v3/schemas/{objectType}?archived=true durchführen. Sie können einen benutzerdefinierten Objekttyp nur löschen, nachdem alle Objektinstanzen von diesem Typ, alle Zuordnungen und benutzerdefinierten Objekteigenschaften gelöscht wurden.

Im Folgenden finden Sie eine Demonstration zum Erstellen eines benutzerdefinierten Beispielobjekts. Die vollständigen Informationen der angezeigten Anfragen finden Sie auf der Registerkarte „Objektdefinition“ oben im Artikel.

In dieser Demonstration wird Folgendes behandelt:

1. Das Erstellen eines benutzerdefinierten Objektschemas.
2. Das Erstellen eines benutzerdefinierten Objektdatensatzes.
3. Das Zuordnen eines benutzerdefinierten Objektdatensatzes zu einem HubSpot-Kontakt.
4. Das Erstellen einer neuen Zuordnungsdefinition zwischen dem benutzerdefinierten Objekt und dem HubSpot-Ticket.
5. Das Erstellen einer neuen Eigenschaftsdefinition.
6. Das Aktualisieren des Objektschemas (d. h. secondaryDisplayProperties) mit der neuen Eigenschaft.
   

   ---

Ziel: Ein Autohaus namens CarSpot möchte seinen Bestand mithilfe eines benutzerdefinierten Objekts in HubSpot speichern. Um die Fahrzeughaltung und die Käufe von Fahrzeugen nachzuverfolgen, ordnet CarSpot Autos Kontaktdatensätzen zu. In Rahmen dieses Plans verfolgt CarSpot auch die Fahrzeugwartung mithilfe von HubSpot-Tickets und benutzerdefinierten Eigenschaften nach.

Erstellen des Objektschemas

CarSpot muss ein Objektschema erstellen, das die folgenden Attribute als Eigenschaften darstellen kann: 

1. Zustand (neu oder gebraucht): Enumeration
2. Datum des Eingangs beim Händler: Datum
3. Jahr: Zahl
4. Automarke: Zeichenfolge
5. Modell: Zeichenfolge
6. VIN: Zeichenfolge (eindeutiger Wert)
7. Farbe: Zeichenfolge
8. Kilometerstand: Zahl
9. Preis: Zahl
10. Anmerkungen: Zeichenfolge

Das Autohaus definiert außerdem eine Verknüpfung zwischen seinem benutzerdefinierten Objekt und dem Standard-Kontaktobjekt, damit es Autos mit potenziellen Käufern verknüpfen kann. 

Nach das Datenmodell von CarSpot abgeschlossen ist, erstellt es das Objektschema, indem es eine POST-Anfrage an /crm/v3/schemas mit dem folgenden Anfragetext durchführt:alles

Erstellen eines benutzerdefinierten Objektdatensatzes

Mit dem erstellten benutzerdefinierten Objekt kann CarSpot jetzt Datensätze im Objekt für jedes Auto in seinem Bestand erstellen.

Es erstellt sein erstes Auto, indem es eine POST-Anfrage an /crm/v3/objects/2-3465404 mit dem folgenden Anfragetext durchführt:

Da der Datensatz erstellt ist, kann CarSpot den id-Wert verwenden, um das Auto später einem vorhandenen Kontakt zuzuordnen.

Zuordnen des benutzerdefinierten Objektdatensatzes zu einem anderen Datensatz

Mit der ID des neuen Fahrzeugdatensatzes (181308) und der ID eines anderen Datensatzes können Sie einen benutzerdefinierten Objektdatensatz einem Datensatz eines anderen Objekts zuordnen.

Um eine Zuordnung zu erstellen, führen Sie eine PUT-Anfrage an /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType} durch. Wenn die Objektbeziehung bereits definiert ist, führen Sie eine GET-Anfrage an crm/v3/schemas/{objectType} durch, um den associationType-Wert zu bestimmen.

Beispielsweise kann CarSpot mit der Kontakt-ID 51 und dem Zuordnungstyp 75 den Fahrzeugdatensatz einem Kontakt zuordnen. Mithilfe der obigen IDs wird die Anfrage-URL wie folgt erstellt:

https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75

Definieren einer neuen Zuordnung

CarSpot möchte nun damit beginnen, die nach dem Verkauf geleisteten Dienstleistungen für seine Autos nachzuverfolgen. Dazu verwendet es HubSpot-Tickets, um alle durchgeführten Wartungsarbeiten zu protokollieren.

Um Verknüpfungen zwischen Autos und Tickets zu ermöglichen, erstellt es eine neue Zuordnung, indem es eine POST-Anfrage an /crm/v3/schemas/2-3465404/associations mit dem folgenden Anfragetext durchführt:

Definieren einer neuen Eigenschaft

Beim Nachverfolgen der Wartung erkennt CarSpot eine Möglichkeit, Wartungsdienste in Paketen zu bündeln. Um diese Wartungspakete in einzelnen Fahrzeugdatensätzen nachzuverfolgen, erstellt das Autohaus eine neue Enumerationseigenschaft, die die verfügbaren Pakete enthält.

Um eine neue Eigenschaft zu definieren, führt es eine POST-Anfrage an /crm/v3/properties/2-3465404 mit dem folgenden Anfragetext durch:

Wenn nun ein Techniker einen Kontaktdatensatz öffnet, dem ein Fahrzeug zugeordnet ist, wird die Eigenschaft auf der Karte für benutzerdefinierte Objekte in der Seitenleiste angezeigt:

Da CarSpot weiterhin HubSpot nutzt, findet es wahrscheinlich noch mehr Möglichkeiten, dieses benutzerdefinierte Objekt mithilfe der HubSpot-API zu verfeinern und zu erweitern. Es könnte sich sogar dazu entschließen, dynamische Seiten mithilfe seiner benutzerdefinierten Objektdaten zu erstellen.