FAQ: API

1. Wie kann ich mich mit meinem API-Token verbinden und authentifizieren? 

Wie Sie Ihre Abfrage formulieren, hängt von der HTTP-Methode und dem Inhaltstyp ab, die Sie angeben. Entsprechend der GraphQL-Spezifikation kann die Anfrage entweder als GET oder POST gesendet werden. 

Wenn Sie eine GET-Anfrage senden,

Wenn Sie eine GET-Anfrage senden, muss für die Parameter im Abfrage-String eine korrekte Esacape-Sequenz vorliegen. 

Wenn Sie eine POST-Anfrage senden,

Wenn Sie eine POST-Anforderung senden, sollte diese wie in diesem Artikel beschrieben einen JSON-kodierten Datenkörper enthalten.

Verwenden Sie die folgende URL für Ihre GET- und POST-Anfragen: 

https://api.matterport.com/api/models/graph

Beispiel einer HTTP-GET-Anfrage (unter Verwendung der obigen URL): 

https://api.matterport.com/api/models/graph?query=query{%20models{%20totalResults%20results%20{%20id%20name%20created%20modified%20visibility%20}}}

Autorisierung: Basic <API-Anmeldeinformationen> 

Beispiel einer cURL-Anfrage: 

curl \
--user [apiKey]:[apiSecret] \
-v 'https://api.matterport.com/api/models/graph?query=\{models\{totalResults%20results\{id%20created%20modified%20visibility\}\}\}'

Beachten Sie die obigen Symbole aus der cURL-Anfrage. Es handelt sich um eine Esacape-Sequenz für die Bash-Programmierung. Da cURL keine automatische URL-Kodierung von Leerzeichen vornimmt, wird das %20 hinzugefügt. 

2. Wie kann ich Panoramabilder abrufen? 

Panoramabilder sind derzeit nur als Skyboxen verfügbar.

Was ist eine Skybox?  

Eine Skybox besteht aus sechs Bildern. Jedes Bild wird einzeln auf die Form eines Würfels projiziert, d. h. oben, unten, links, rechts, vorne und hinten. Skyboxen werden in 4K wiedergegeben und mit Positions- und Rotationsdaten versehen. 

Abfrage von Skybox-Bildern  

Verwenden Sie die folgende Abfrage: 

query {
model(id:"$modelId") {
assets {
panos {
perspective {
options {
format
resolutions
}
skybox(resolution: "4k") {
id
status
format
children
}
position {x,y,z}
rotation {x,y,z,w}
}
}
}
}
}

3. Die Koordinaten des Showcase-SDK und der Modell-API scheinen nicht übereinzustimmen. Wie kann ich beide verwenden?

Das ist ein wenig verwirrend, aber zu erwarten. Das Showcase-SDK ist so konzipiert, dass es aus der Kameraperspektive arbeitet. Daher dreht sich sein Koordinatensystem, um die Y-Achse (Höhe) und die Z-Achse (Tiefe) zu bestimmen. Wenn Sie ein Matterpak herunterladen würden, würden Sie sehen, dass alle Koordinateninformationen im Zusammenhang mit der Z-Achse nach oben ausgerichtet sind. Das SDK verbirgt dies, indem es nur bestimmte Informationen preisgibt. 

right.png

Der Pseudocode für die Übersetzung lautet wie folgt:  

def fromSdkToApi(x, y, z) = { x, -z, y }

def fromApiToSdk(x, y, z) = { x, z, -y }

Beachten Sie, dass die obige Übertragung seltsam erscheinen mag, weil sowohl die Z- als auch die Y-Koordinaten gespiegelt sind und eine von ihnen spiegelverkehrt ist. 

4. Ich kann die Änderungen, die ich mit der Modell-API vornehme, nicht sofort sehen. Was kann ich tun? 

Dies geschieht aufgrund des Caching in unserem CDN. Bei einer Bearbeitung/Veröffentlichung wird der CDN-Cache vollständig geleert, obwohl wir dies derzeit nicht für jede Bearbeitung auf der API-Ebene tun. 

Um zu überprüfen, ob es sich um ein Problem in Zusammenhang mit dem CDN-Cache handelt, können Sie das Modell in einem privaten oder Inkognito-Fenster betrachten. Authentifizierte Benutzer umgehen den Cache, anonyme Betrachter jedoch nicht. Wenn dem so ist, sollten die Änderungen innerhalb einer Stunde für alle sichtbar sein. 

5. Kann ich ein 3D-Netz eines Modells mit der API bearbeiten?

Nein, die API kann derzeit nur Modellinformationen, Assets, Mattertags, Beschriftungen und Pakete abrufen und definieren.

6. Wie kann ich alle Modelle mittels Anfragen in Python abfragen? 

Verwenden Sie die folgende Abfrage: 

import requests 

token = 'Your API token'
secret = 'Your secret API token'
endpoint = 'https://api.matterport.com/api/models/graph'
query = { 'query' :
'''
query {
models(query: "*"){
totalResults
results{ id }
}
}
'''
}
auth = (token, secret)
headers = {'content-type': 'application/json', 'accept':'gzip'}
r = requests.post(endpoint, json=query, auth=auth, headers=headers)

if(r.ok):
print(r.json())
else:
print(r.status_code)

7. Wie kann ich mit Node.js alle Modelle mit Fetch abfragen?

const { default: fetch } = require("node-fetch");

const token = "Your API token";
const secret = "Your secret API token";

const auth = Buffer.from(token + ':' + secret).toString('base64');

const endpoint = "https://api.matterport.com/api/models/graph";

const body = JSON.stringify({
query: `
query {
models(query: "*"){
totalResults
results{ id }
}
}
`
});

fetch(endpoint, {
method: 'POST',
headers: {
'Authorization': `Basic ${auth}`,
'Content-type': 'application/json'
},
body: body,
})
.then(res => res.json())
.then(data => console.log(data))

8. Ich bin ein Mitwirkender mit Admin-Bearbeitungsrechten für ein Unternehmen. Warum kann ich keine Modelle in diesem Konto abfragen? 

Wenn Sie den Status eines Mitwirkenden (nicht den eines Administrators) haben, können Sie nicht über die API auf Modelle zugreifen. Wenn Sie Zugriff benötigen, haben Sie zwei Möglichkeiten: 

  1. Fordern Sie einen Administrator des Kontos auf, den Bereich auf Sie zu übertragen.
  2. Bitten Sie den Administrator des Kontos, Ihnen seine API-Tokens mitzuteilen.
    • Mit einem API-Token erhalten Sie Zugriff auf alle Modelle, die zum Konto des Administrators gehören.