Preguntas frecuentes - API

1. ¿Cómo me puedo conectar y autentificar con el token de mi API?

La forma de escribir la consulta depende del método HTTP y del tipo de contenido que especifique. Según la especificación GraphQL, la solicitud puede enviarse como GET o POST.

Si envía una solicitud de GET:

Los parámetros se deben escapar correctamente en la cadena de consulta.

Si envía una solicitud de POST:

Debe incluir un cuerpo codificado en JSON, ilustrado en este artículo.

Utilice esta URL en sus solicitudes de GET y POST:

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

Ejemplo de solicitud de GET en HTTP (utilizando la URL anterior):

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

Autorización: <credenciales api> básicas

Ejemplo de solicitud de cURL:

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

Observe los símbolos de arriba tomados de la solicitud de cURL: son escapes para bash. El cURL no codificará automáticamente los espacios en blanco de la URL, por lo que se añade el %20.

2. ¿Cómo se recuperan las imágenes panorámicas?

Actualmente, las imágenes panorámicas solo están disponibles como skyboxes.

¿Qué es un skybox?

Un skybox se compone de seis imágenes, cada una de las cuales se proyecta individualmente sobre la forma de un cubo, es decir: los lados superior, inferior, izquierdo, derecho, frontal y posterior. Los skyboxes se representan en 4K y vienen acompañados de datos de posición y rotación.

Cómo recuperar imágenes de skybox

Utilice la siguiente consulta:

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. Al parecer, las coordenadas del SDK de Showcase y de la API del modelo no coinciden. ¿Cómo puedo utilizar las dos?

Esto es un poco confuso, pero es el comportamiento previsto. El SDK de Showcase está diseñado para trabajar desde la perspectiva de la cámara, por lo que su sistema de coordenadas gira para determinar el eje Y (altura) y el eje Z (profundidad). Si descargara un paquete MatterPak, encontraría toda la información de las coordenadas con el eje Z hacia arriba. El SDK oculta esto exponiendo solo cierta información.

right.png

El pseudocódigo para hacer la conversión es el siguiente: 

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

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

Tenga en cuenta que la conversión anterior puede parecer extraña porque las coordenadas Z e Y están volteadas y una está invertida.

4. No puedo ver de inmediato los cambios que estoy haciendo con la API del modelo. ¿Qué debo hacer?

Esto sucede debido al almacenamiento en caché de nuestra red de distribución de contenidos (CDN). Un flujo de edición/publicación vaciará completamente la caché de la CDN, aunque actualmente no lo hacemos para cada edición en la capa de la API. 

Una forma de verificar que está experimentando un problema de caché de la CDN es mirar el modelo en una ventana de navegación privada o de incógnito. Los usuarios autentificados podrán eludir la caché, pero los espectadores anónimos no podrán hacerlo. Si este es el caso, los cambios deberían ser visibles para todos antes de una hora.

5. ¿Puedo manipular una malla 3D de un modelo con la API?

No, actualmente la API solo puede obtener y establecer detalles del modelo, activos, etiquetas Mattertag, etiquetas y paquetes.

6. ¿Cómo puedo consultar todos los modelos con Python mediante solicitudes?

Utilice la siguiente consulta:

import requests 

token = 'Token de la API'
secret = 'Token secreto de la API'
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. ¿Cómo puedo consultar todos los modelos con Node.js mediante el comando fetch?

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

const token = "Token de la API";
const secret = "Token secreto de la API";

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. Soy un colaborador con privilegios de edición de administrador para una organización. ¿Por qué no puedo consultar ningún modelo de la cuenta?

Si tiene permisos de colaborador (y no de administrador), no puede acceder a los modelos a través de la API. Si necesita acceso, tiene dos opciones:

  1. Solicitar que un administrador de la cuenta le transfiera el espacio.
  2. Hacer que el administrador de la cuenta comparta sus tokens de API con usted.
    • Un token de API le dará acceso a todos los modelos que pertenezcan a la cuenta del administrador.