So verwenden Sie die Matterport-API

Unsere Entwickler-Community steckt voller Branchenfachleute, die Matterport in ihre täglichen Arbeitsabläufe integrieren möchten. Diese Herausforderung möchten wir lösen, und der erste Schritt dazu ist das Öffnen unserer API für Architekten, Ingenieure und alle anderen Fachleute, die sich näher mit unserer Plattform befassen möchten

Wir bieten jetzt ein Entwickler-Toolset, mit dem Entwickler sich direkt mit dem Back-End-Datenspeicher von Matterport verbinden können. Gleichzeitig können Kunden programmgesteuert auf ihre Modelle zugreifen. Vom direkten Zugriff auf Daten über das Modifizieren von Inhalten bis hin zum Verwalten eines Modellstatus und dem Kauf von Zusatzleistungen – wir möchten, dass unsere Entwickler die volle Kontrolle haben.

Dokumentation 

In unserem Referenzleitfaden finden Sie weitere Informationen über unsere aktuellen GraphQL-API-Ressourcen. Dort können Sie auch auf unsere interaktive Konsole zugreifen, mit der Sie in begrenztem Umfang mit der GraphQL-API experimentieren können. 

Um auf diese interaktive Konsole zugreifen zu können, müssen Sie als Administrator in der Matterport-Cloud (my.matterport.com) angemeldet sein.

Anleitung 

Generieren von API-Schlüsseln

  1. Rufen Sie die Matterport-Cloud auf (my.matterport.com).
  2. Klicken Sie im Drop-down-Menü auf der rechten Seite auf „Konto“.
  3. Wählen Sie „Entwicklertools“ aus.
  4. Scrollen Sie zum Abschnitt „API-Tokenverwaltung“.
    • Dort können Sie API-Schlüssel anfordern und zurückrufen. 

Sie müssen einen API-Schlüssel erstellen, mit dem Sie auf unseren API-Endpunkt zugreifen können. Bitte beachten Sie, dass Sie bis zu fünf Schlüssel für die Verwendung in verschiedenen Anwendungen, die Sie bauen möchten, generieren können. Neue von Ihnen erstellte Schlüssel enthalten Folgendes: 

  1. Token-Geheimnis 
    • Es wird nur ein Mal gezeigt – Sie sollten es also kopieren und sicher abspeichern. 
  2. Token-ID
    • Sie wird auf der Seite „Einstellungen“ angezeigt

API-Schlüssel sind „Admin-“ oder „Voller-Zugriff“-Schlüssel. Das bedeutet, dass sie Nutzern administrative Rechte für das Kundenkonto erteilen. Wenn sie die API mit dem generierten API-Schlüssel nutzen, können Entwickler mit der API alle administrativen Funktionen nutzen. Dazu zälen das Archivieren von Modellen und das Erwerben von Grundrissen und MatterPaks. Bitte denken Sie daran, wenn Sie Ihre API-Schlüssel teilen: Wir empfehlen Ihnen nicht, Ihre API-Schlüssel mit dritten Unternehmen oder Entwicklern zu teilen.

Bitte beachten Sie, dass bei Konten standardmäßig nur der Sandbox-Modus aktiviert ist. Weitere Informationen zum Sandbox-Modus finden Sie in unseren Hinweisen zur Verfügbarkeit und Preisgestaltung von Entwicklertools.

Endpunkt-Verbindung 

  1. Greifen Sie über folgende Adresse auf den API-Endpunkt zu: https://api.matterport.com/api/models/graph
  2. Nutzen Sie die Token-ID als Benutzernamen.
  3. Nutzen Sie das Token-Geheimnis als Passwort.
    • Beispiel: Autorisierung: Basic <base64_encode(<Token-ID>:<Token-Geheimnis) 

Alle Standard-HTTP-Bibliotheken sollten diesen Prozess unterstützen. Achten Sie jedoch darauf, Ihre präemptive Autorisierung auf „wahr“ zu stellen.   

Fehlercodes 

Alle Fehler auf Anwendungsebene haben „Codes“ in ihren Fehlererweiterungen. Mit dem Leitfaden unten können Sie die häufigsten Fehlercodes erkennen und die Fehler beheben. 

   1. request.unauthenticated 

Es liegt kein Autorisierungstoken vor oder der Autorisierungstoken ist abgelaufen. 

   2. request.unauthorized 

Der Benutzer hat versucht, auf eine Funktion oder ein Feld zuzugreifen, die bzw. das nicht zulässig ist. 

   3. request.invalid 

Die Grafikanfrage konnte nicht verarbeitet werden. 

   4. error.internal 

Der Server konnte die Anfrage nicht verarbeiten. 

   5. not.found 

Das angeforderte Objekt existiert nicht. Dieser Fehler wird angezeigt, wenn Sie das spezifische ID-Feld in der zugehörigen Funktion nutzen. 

   6. not.unique 

Es wurde versucht, einen einzelnen Datensatz aus einem sekundären Index zu ziehen. Auf die Anfrage trafen jedoch mehrere Datensätze zu. Das ist häufig der Fall, wenn verschiedene Modelle eine identische interne ID haben. 

   7. quota.exceeded 

Änderungen durch die Ressourcen begrenzt – zum Beispiel der Versuch, mehr Modelle zu aktivieren, als mit dem Abonnement möglich ist. 

Beispiele für Codeschnipsel 

Sehen Sie sich zunächst diese Beispiele für Codeschnipsel an. 

Häufig gestellte Fragen 

1. Was ist eine API? 

API steht für „Application Programming Interface“ – also eine Programmierschnittstelle. Eine API ist ein Kommunikationsprotokoll zwischen verschiedenen Teilen eines Computerprogramms. Der Hauptzweck einer API ist es, die Implementierung und Wartung von Software zu vereinfachen. 

Mit Matterport-APIs können Entwickler (oder Kunden) ihre Systeme oder Anwendungen programmatisch direkt mit dem Matterport-System verbinden und so auf Daten zugreifen und Änderungen vornehmen. 

2. Matterport bietet auch ein „SDK“ an – worin liegt der Unterschied? 

Vor der Betaversion der Matterport-API haben Matterport-Entwickler das Showcase-SDK (Software Development Kit) genutzt. Die Beta-API ist eine ergänzende Funktion. Unten sehen wir uns die Unterschiede an. 

Showcase-SDK 

Das Showcase-SDK ist ein Set aus Programmierbefehlen, mit dem Entwickler die Funktionen von Showcase erweitern können, selbst wenn Showcase direkt in eine andere Seite oder Plattform eingebettet ist. Sie können es sich wie eine dünne, unsichtbare Ebene vorstellen, die auf dem Showcase-iFrame sitzt, ausschließlich  auf der Entwicklerseite. Vor diesem Hintergrund gilt: Das SDK wirkt sich nur auf die Erfahrung auf der Entwicklerseite aus. Modelle, die auf mehreren Sites geteilt wurden, sind also nur auf der Entwicklerseite betroffen, auf der das SDK genutzt wurde. 

API

Anders als das SDK verindet die API direkt zum Matterport-Back-End. Das ermöglicht es Entwicklern, eine Reihe von Befehlen zu nutzen – zum Beispiel das Suchen, Lesen von Daten, Ändern von Daten und Aufgeben von Bestellungen. Mit der Matterport-API können Entwickler programmatisch Aktionen durchführen, die Nutzer auf unserer Site tätigen. 

3. Was ist die Modell-API und welche anderen APIs werden in Betracht gezogen?

Die Welt der APIs scheint endlos zu sein. Derzeit sammelt Matterport verschiedene Befehle in Unterkategorien, die wir Entwicklern zur Verfügung stellen: 

Modell-API-Befehle

Mit diesen Befehlen können Modelldaten gesucht, gelesen und/oder geändert werden. Was gehört alles zu den Modelldaten? Modelldetails (wie der Name und die Adresse des Spaces), URLs zum Teilen, Bilder, Videos, Standortdaten, die OBJ-Mesh-Datei, die Punktwolke-Datei, Panoramabilder, Positionspunkte und Mattertags. 

Ingest-API-Befehle 

Mit diesen Befehlen wird eine Sammlung aus Panoramabildern direkt an die Matterport-Vision-Pipeline gesendet, um eine 3D-Rekonstruktion zu erstellen. Neben Panoramabildern können Entwickler auch zusätzliche Metadaten übermitteln, zum Beispiel eine Panoramasequenz, ein Panorama des Bodens oder andere Positionsdaten. Allgemein gilt: Je mehr Metadaten bereitgestellt werden, desto höher sind die Chancen auf eine erfolgreiche 3D-Konstruktion. 

Wärend wir weiter an dieser Lösung arbeiten, hoffen wir, Kunden unterstützen zu können, die eine Sammlung von Panoramabildern mit verschiedenen omnidirektionalen Kameras aufgenommen haben, die zuvor nicht mit unserer Plattform kompatibel waren. 

Konto-API-Befehle 

Mit diesen Befehlen können Nutzer und Ordner verwaltet werden, darunter auch Bereitstellung und das Einrichten von Genehmigungen. 

Service-API-Befehle 

Diese Befehle können Entwickler nutzen, um programmatisch unsere Zusatzleistungen zu entdecken und darauf zuzugreifen sowie Bestellungen aufzugeben. Die Zusatzleistungen werden neben den Matterport-Modellen angeboten und umfassen unter anderem MatterPaks und Grundrisse. 

Veröffentlichung-API-Befehle 

Mit diesen Befehlen können Entwickler programmatisch alle Publishing-Plattformen entdecken und nutzen, die Matterport aktuell unterstützt. Dazu gehören Google Street View, Vrbo, realtor.com und homes.com.

4. Auf welche Konten kann ich mit der API zugreifen? 

Wir empfehlen, die API nur zu nutzen, um das Konto und die Modelle des Kunden aufzurufen. Bitte denken Sie daran, dass der API-Token ein Set mit administrativen Berechtigungen ist und vollen Zugriff auf das Konto ermöglicht. Es ist sogar möglich, über die API Käufe zu tätigen. 

5. Wie fange ich an? 

Sie müssen einen API-Token anfordern. Befolgen Sie dazu einfach die unten stehende Anleitung. 

  1. Rufen Sie die Matterport-Cloud auf (my.matterport.com).
  2. Klicken Sie im Drop-down-Menü auf der rechten Seite auf „Konto“. 
  3. Wählen Sie „Entwicklertools“ aus. 
  4. Scrollen Sie zum Abschnitt „API-Tokenverwaltung“. 
    • Dort können Sie API-Schlüssel anfordern und zurückrufen. 

6. Haben Sie noch Fragen? 

Sehen Sie sich unsere umfassenden häufig gestellten Fragen zur Modell-API an. 

Haben Sie Fragen? Anfrage einreichen