Comment utiliser l’API Matterport

Notre communauté de développeurs compte de nombreux professionnels de l’industrie qui veulent intégrer Matterport à leurs workflows quotidiens - nous nous engageons à relever ce défi, et cela commence par l’ouverture de notre API aux architectes, ingénieurs et à tous les autres professionnels qui veulent plonger plus profondément dans notre plateforme.

Nous offrons maintenant un ensemble d’outils de développeur qui permettra aux développeurs de se connecter directement au magasin de données dorsal de Matterport, tout en permettant aux clients d’intervenir sur leurs modèles de manière programmatique. De l’accès direct aux données à l’achat de services à valeur ajoutée, en passant par la modification du contenu et la gestion du statut d’un modèle, nous voulons que nos développeurs gardent le plein contrôle.

Documentation 

Vous pouvez en apprendre plus sur nos capacités actuelles d’API GraphQL dans notre guide de référence - cela vous donnera également accès à notre console interactive, où vous pourrez expérimenter l’API GraphQL sur une base limitée.

Pour accéder à la console interactive, vous devrez être connecté à Matterport Cloud (my.matterport.com) avec des identifiants d'admin.

Instructions

Générer des clés d'API

  1. Accédez à Matterport Cloud (my.matterport.com)
  2. Cliquez sur le menu déroulant « Compte » à droite
  3. Sélectionnez « Outils de développeur »
  4. Faites défiler vers la section intitulée « Gestion des jetons API »
    • D'ici, vous pouvez demander et révoquer des clés d'API.

Vous devrez générer une clé d'API qui vous permettra de vous connecter à notre point de terminaison d'API. N'oubliez pas que vous pouvez générer jusqu’à cinq clés à utiliser dans les différentes applications que vous souhaitez construire. Lorsque vous créez une nouvelle clé, vous découvrez la page suivante :

  1. Secret de jeton
    • Ceci n’apparaît qu'une fois - assurez-vous de le copier et de l’enregistrer en toute sécurité.
  2. ID du jeton
    • Il s'affichera dans la page des paramètres.

Les clés d'API sont des clés « admin » ou « all-access ». Cela signifie qu’elles accordent aux utilisateurs des informations d’identification administratives pour le compte client. À l’aide de l’API avec la clé d'API générée, les développeurs peuvent effectuer toutes les fonctions administratives à l’aide de l’API, y compris les modèles d’archivage et l’achat de plans d’étage et de MatterPaks. Il est important de ne pas l'oublier lors du partage de vos clés d'API - nous vous conseillons fortement de ne pas partager vos clés d'API avec des sociétés ou des développeurs tiers.

Veuillez noter que par défaut, seul le mode Sandbox est activé. Pour plus d’informations sur le mode Sandbox, veuillez vous référer à notre disponibilité et aux prix des outils de développement.

Connectez-vous au point de terminaison

  1. Accédez au point de terminaison de l’API à l'adresse : https://api.matterport.com/api/models/graph 
  2. Utilisez l’ID de jeton comme nom d’utilisateur
  3. Utilisez le Secret du jeton comme mot de passe
    • Exemple : Authorization: de base <base64_encode(<ID de jeton> :<Secret du jeton) 

Toutes les bibliothèques http standard devraient prendre en charge ce processus, mais assurez-vous de définir votre droit de préemption sur « vrai ».   

Codes d'erreur

Toutes les erreurs au niveau des applications auront des « codes » dans leurs extensions d’erreur - utilisez le guide ci-dessous pour identifier et dépanner les codes d’erreur courants.

   1. request.unauthenticated 

Aucun jeton d’autorisation n’est présent, ou le jeton d’autorisation a expiré.

   2. request.unauthorized 

L’utilisateur a tenté d’accéder à une opération ou à un champ non autorisé.

   3. request.invalid 

La requête graphique n’a pas pu être traitée.

4. erreur.internal

Le serveur n’a pas pu traiter la demande.

   5. not.found 

L’objet demandé n’existe pas - vous verrez cette erreur lors de l’utilisation du champ d’identification spécifique dans l’opération associée.

6. not.unique

Une tentative a été faite pour récupérer un seul enregistrement à partir d’un index secondaire, mais plusieurs enregistrements correspondaient à la requête soumise. Cela arrive souvent lorsque plusieurs modèles ont le même ID interne.

7. quota.exceeded

Mutations de ressources limitées - par exemple, trop grand nombre de tentatives d'activation de modèles en raison de limitations d’abonnement.

Exemples d’extraits de code

Pour commencer, référez-vous à ces exemples d’extraits de code.

FAQ

1. Qu’est-ce qu’une API ?

API signifie « interface de programmation d'application » - il s’agit d’un protocole de communication entre les différentes parties d’un programme informatique. L’objectif principal d’une API est de simplifier la mise en œuvre et la maintenance des logiciels.

Les API Matterport permettent aux développeurs (ou aux clients) de connecter leurs systèmes ou applications directement au système Matterport afin d’accéder aux données et de les modifier.

2. Matterport offre également un « SDK » - quelle est la différence ?

Avant la version bêta de l'API Matterport, les développeurs Matterport utilisaient principalement le Showcase SDK (kit de développement logiciel). L'API bêta est une fonctionnalité supplémentaire - passons aux différences ci-dessous.

Showcase SDK 

Le Showcase SDK est un ensemble de commandes de programmation qui peuvent être utilisées par les développeurs pour étendre les capacités de Showcase, même si Showcase est directement imbriqué dans un autre site ou sur une autre plateforme. Considérez-le comme une mince couche invisible qui se trouve sur le dessus de la vitrine iFrame, seulement dans la page développeur. Dans cet esprit, le SDK n’affecte l’expérience que sur une page de développeur par utilisation. À ce titre, les modèles qui ont été partagés sur plusieurs sites ne sont affectés que sur la page du développeur où le SDK a été appliqué.

API

Contrairement à la SDK, l’API se connecte directement au système dorsal de Matterport. Cela permet aux développeurs d’effectuer une variété de commandes, comme la recherche, la lecture de données, la modification des données et le placement de commandes. L’API Matterport permet aux développeurs d’effectuer de manière programmatique les actions que les clients effectuent sur notre site.

3. Quelle est l'API du modèle et quelles autres API sont à l’étude ?

Le monde des API est immense - pour l’instant, Matterport regroupe les différentes commandes que nous mettons à la disposition des développeurs en sous-catégories :

Commandes API de modèle

Ces commandes recherchent, lisent et/ou modifient les données du modèle. Qu’est-ce qui constitue des données modèles ? Détails du modèle (comme le nom et l’adresse de l’espace), partage d’URL, d’images, de vidéos, de données de position, le fichier de maille OBJ, le fichier cloud point, l’imagerie panoramique, les points de position et les Mattertags.

Ingérer les commandes d'API

Ces commandes envoient une collection d’images panoramiques directement dans le pipeline de vision Matterport - le tout dans le but de tenter une reconstruction en 3D. Outre les images panoramiques, les développeurs peuvent envoyer des métadonnées supplémentaires, comme une séquence panos, un panos du sol et d’autres données de position. Globalement, plus les métadonnées fournies sont nombreuses, plus les chances de succès de la reconstruction en 3D sont élevées.

À mesure que cette solution mûrit, nous espérons soutenir les clients qui ont pris une collection d’images panoramiques à l’aide de différentes caméras à 360° qui étaient auparavant incompatibles avec notre plateforme.

Commandes des API de compte

Ces commandes gèrent les utilisateurs et les dossiers, y compris l’approvisionnement et la configuration d'autorisations.

Commandes d'API de service

Ces commandes permettent aux développeurs de découvrir, de passer des commandes et d’accéder aux services à valeur ajoutée que nous offrons en plus des modèles Matterport (comme les MatterPaks et les plans d’étage).

Publier les commandes d'API

Ces commandes permettent aux développeurs de découvrir et d’utiliser de manière programmatique toutes les plateformes d’édition que Matterport prend en charge aujourd’hui. Il s’agit notamment de Google Street View, Vrbo, realtor.com, et homes.com.

4. À quels comptes puis-je accéder à l’aide de l’API ?

Nous recommandons uniquement d’utiliser l’API pour accéder au compte et aux modèles du client.N'oubliez pas que le jeton API est essentiellement un ensemble d’informations d’identification administratives, et fournit un accès complet au compte (même pour effectuer des achats via l'API).

5. Comment commencer ?

Vous devrez demander un jeton API - suivez les brèves instructions ci-dessous.

  1. Accédez à Matterport Cloud (my.matterport.com)
  2. Cliquez sur le menu déroulant « Compte » à droite
  3. Sélectionnez « Outils de développeur »
  4. Faites défiler vers la section intitulée « Gestion des jetons API »
    • D'ici, vous pouvez demander et révoquer des clés d'API.

6. D'autres questions ?

Consultez notre FAQ d'API de modèle étendue.

Vous avez d’autres questions ? Envoyer une demande