REST API

Το REST API επιτρέπει στο δικό σας λογισμικό να κάνει ό,τι κάνει η εφαρμογή: έργα και μετρήσεις τους, φακέλους και τον κατάλογο προϊόντων· στο Enterprise, τον οργανισμό σας, όπως τον διαχειρίζεται η σελίδα Enterprise· στο Open Guest, τον σύνδεσμο επισκέπτη, τα έργα επισκεπτών και τα αιτήματα προσφοράς. Απαντά σε JSON. Η πλήρης αναφορά, με κάθε πεδίο και παράδειγμα, είναι η τεκμηρίωση API· αυτή η σελίδα είναι η επισκόπηση.

Για να ανοίξετε την τεκμηρίωση από την εφαρμογή, μεταβείτε στο codeΠρογραμματιστής > apiREST API και πατήστε menu_bookΠροβολή τεκμηρίωσης.

Βασική διεύθυνση URL#

Κάθε αίτημα πηγαίνει στη διεύθυνση:

https://api.measuremaponline.com/api/v2

Έλεγχος ταυτότητας#

Στείλτε το κλειδί API σας, ως έχει, στην κεφαλίδα Authorization κάθε αιτήματος. Δημιουργήστε το κλειδί στη σελίδα Προγραμματιστής: δείτε τα κλειδιά API.

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

Κάθε αίτημα ελέγχεται με βάση την πρόσβαση του κλειδιού (για παράδειγμα, Projects Ανάγνωση), τη συνδρομή σας και, για αίτημα που στέλνεται από ιστοσελίδα, τους περιορισμούς ιστότοπων του κλειδιού. Κρατήστε τα κλειδιά που μπορούν να αλλάξουν δεδομένα στον διακομιστή σας: δείτε κρατήστε το κλειδί σας ασφαλές.

Live και sandbox#

Υπάρχει μία βασική διεύθυνση URL και για τα δύο. Το κλειδί αποφασίζει: ένα κλειδί sandbox διαβάζει και γράφει έργα, φακέλους και προϊόντα sandbox, που τα live κλειδιά δεν βλέπουν ποτέ. Οι χρήστες, οι θέσεις και οι ομάδες του οργανισμού σας είναι ίδιοι και στα δύο, οπότε για να τους αλλάξετε χρειάζεστε live κλειδί. Τα έργα επισκεπτών που δημιουργούνται με κλειδί sandbox δεν χρεώνονται ποτέ και τα έργα sandbox δεν μπορούν να ενσωματωθούν στον ιστότοπό σας. Τα tokens αναφέρουν το περιβάλλον στο οποίο ανήκουν.

Τι καλύπτει το API#

Μερικά πράγματα που πρέπει να ξέρετε:

• Ένα κλειδί φτάνει στα έργα του δικού του λογαριασμού και, στο Enterprise, σε αυτά των χρηστών του οργανισμού.
• Η διαγραφή ενός έργου το βάζει στον Κάδος απορριμμάτων, όπως στην εφαρμογή, και μόνο ο δημιουργός του μπορεί να το κάνει· διαγράψτε το οριστικά από τον Κάδος απορριμμάτων με forever=true. Η διαγραφή ενός φακέλου βάζει τα έργα του στον Κάδος απορριμμάτων.
• Στις μετρήσεις ενός έργου, ένα σχήμα παραθέτει τα προϊόντα του στο productIds, με σειρά· το productId είναι το πρώτο από αυτά.
• Το /projects/{pid}/mmp δίνει το ίδιο αρχείο .mmp που εξάγει η εφαρμογή. Το σχήμα του δημοσιεύεται στο github.com/blueblinkone/mmp-validator. Νέα στοιχεία προστίθενται πάντα ως προαιρετικά, ώστε ένας αναγνώστης που γράφτηκε για παλαιότερο αρχείο να συνεχίζει να λειτουργεί.
• Στο Open Guest, ένα έργο επισκέπτη που ξεκινά μέσω του API (POST /open-guest/projects) προσμετράται στη χρήση και τον προϋπολογισμό σας στο Open Guest, όπως ένα που ξεκινά από τον σύνδεσμο επισκέπτη.
• Στο Open Guest, η ενότητα person_pin_circleΣύνδεσμος επισκέπτη έχει τον οδηγό Open Guest API, με κώδικα για τον διακομιστή και τη σελίδα σας: ο διακομιστής σας παίρνει ένα token από το POST /auth/token με το live κλειδί σας και στέλνει τον επισκέπτη σε ένα νέο έργο δικό του, με συμπληρωμένα τα στοιχεία του.
• Τα άτομα μπαίνουν στον οργανισμό σας μόνο με πρόσκληση (POST /enterprise/invitations), όπως στη σελίδα Enterprise: όποιος δεν έχει λογαριασμό παίρνει έναν και επιλέγει μόνος του κωδικό πρόσβασης. Το API δεν δημιουργεί ποτέ λογαριασμό ούτε ορίζει κωδικό πρόσβασης.
• Η αφαίρεση ενός χρήστη (POST /enterprise/users/{uid}/remove) του αφήνει τον λογαριασμό του· η διαγραφή (DELETE /enterprise/users/{uid}) τον διαγράφει. Και στις δύο περιπτώσεις η δουλειά που έκανε μένει στον οργανισμό, σε νέο φάκελο με το όνομά του, που μοιράζονται οι διαχειριστές σας.
• Όταν ένας επισκέπτης ζητά την προσφορά σας, το GET /open-guest/requests/{pid} απαντά ποιος είναι, τι έγραψε, τι μέτρησε και, με Προϊόντα: Ανάγνωση, την ίδια την προσφορά.
• Στο Open Guest, τα tokens ξεκινούν έργα επισκεπτών για τους επισκέπτες σας. Το POST /auth/iframe/token, που συνδέει έναν επισκέπτη σε έναν ενσωματωμένο χάρτη, προορίζεται για κλειδιά Enterprise.
• Τα προϊόντα δεν διαγράφονται ποτέ μέσω του API, μόνο αρχειοθετούνται, και η τιμή κόστους ενός προϊόντος δεν επιστρέφεται ποτέ.
• Τα κτηματολογικά γεωτεμάχια δεν αποτελούν μέρος του API.

Απαντήσεις και σφάλματα#

Ένα επιτυχές αίτημα απαντά με κατάσταση 200 και JSON (η εξαγωγή .mmp απαντά με XML). Ένα αίτημα που απέτυχε απαντά με κατάσταση σφάλματος και σώμα όπως:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

Δοκιμάστε το API από τη σελίδα Προγραμματιστής#

Το codeΠρογραμματιστής > terminalΔοκιμάστε το API στέλνει πραγματικά αιτήματα με το κλειδί σας και δείχνει ακριβώς τι επιστρέφεται.

1. Επιλέξτε Παραγωγή ή Sandbox.
2. Διαλέξτε ένα Endpoint, όπως «Λίστα των έργων σας», «Λήψη μετρήσεων» ή «Λήψη λογαριασμού». Η λίστα προσφέρει τα endpoints που περιλαμβάνει το πρόγραμμά σας.
3. Συμπληρώστε τις παραμέτρους του. Ένα έργο ή ένα προϊόν επιλέγεται με το όνομά του ανάμεσα σε όσα μπορεί να διαβάσει το κλειδί· όπου χρειάζεται ένα άτομο, συμπληρώνεται για εσάς ο δικός σας λογαριασμός.
4. Πατήστε play_arrowΑποστολή αιτήματος. Η κατάσταση και η απάντηση εμφανίζονται από κάτω.

Προσφέρονται μόνο αιτήματα ανάγνωσης, οπότε η δοκιμή δεν αλλάζει τίποτα, και αυτά τα αιτήματα δεν προσμετρώνται στη χρήση σας. Αν το κλειδί σας δεν έχει την πρόσβαση που χρειάζεται ένα endpoint, η σελίδα σας προειδοποιεί ότι θα απαντήσει με 403.

Webhooks#

Ένα webhook ειδοποιεί τον διακομιστή σας όταν συμβαίνει κάτι, όπως σας ειδοποιούν τα email ειδοποιήσεων. Τα webhooks ανήκουν στα προγράμματα Enterprise και Open Guest.

Ρυθμίστε ένα webhook#

Στο codeΠρογραμματιστής > webhookWebhooks:

1. Πληκτρολογήστε το URL endpoint σας: μια διεύθυνση https:// στο διαδίκτυο. Οι διευθύνσεις σε ιδιωτικά δίκτυα απορρίπτονται και αυτό ελέγχεται ξανά πριν από κάθε παράδοση.
2. Επιλέξτε τα Γεγονότα που θέλετε (δείτε τα συμβάντα). Ένα νέο endpoint ξεκινά με τα συμβάντα που στέλνει το πρόγραμμά σας και πρέπει να είναι επιλεγμένο τουλάχιστον ένα.
3. Πατήστε saveΑποθήκευση. Την πρώτη φορά, η σελίδα δείχνει ολόκληρο το Secret υπογραφής σας. Αντιγράψτε το τότε: αργότερα εμφανίζονται μόνο οι τελευταίοι χαρακτήρες του.
4. Πατήστε sendΑποστολή δοκιμαστικού γεγονότος και διαλέξτε ένα συμβάν.

Μια δοκιμή στέλνει ένα δείγμα αυτού του συμβάντος, με επινοημένες τιμές και "test": true στο data του, στο αποθηκευμένο endpoint σας, ακόμη και όταν το συμβάν δεν είναι επιλεγμένο ή το endpoint είναι απενεργοποιημένο. Για να σταματήσετε όλες τις παραδόσεις, πατήστε delete_outlineΚατάργηση: το endpoint και το secret του διαγράφονται.

Κάτω από τις ρυθμίσεις, το Αναφορά webhook έχει ό,τι χρειάζεστε για να γράψετε το δέκτη: τις κεφαλίδες και το σώμα, κώδικα που ελέγχει την υπογραφή σε Node.js, Python και PHP, και δείγματα δεδομένων για κάθε συμβάν.

Τι λαμβάνει ο διακομιστής σας#

Κάθε συμβάν είναι ένα POST προς το endpoint σας, με σώμα JSON:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

Το id είναι μοναδικό για κάθε συμβάν, το created είναι πότε συνέβη σε χιλιοστά του δευτερολέπτου από την 1η Ιανουαρίου 1970 (UTC), και το τι περιέχει το data εξαρτάται από το συμβάν. Το αίτημα έχει επίσης αυτές τις κεφαλίδες:

• Απαντήστε με κατάσταση 2xx μέσα σε 8 δευτερόλεπτα, πριν από οποιαδήποτε αργή εργασία. Οποιαδήποτε άλλη κατάσταση, ανακατεύθυνση ή λήξη χρόνου μετράει ως αποτυχία.
• Κάθε συμβάν στέλνεται μία φορά και δεν επαναλαμβάνεται ποτέ. Η ενότητα δείχνει την Τελευταία παράδοση και τις Διαδοχικές αποτυχίες.
• Μετά από 10 αποτυχίες στη σειρά, το endpoint απενεργοποιείται και ο κάτοχος λαμβάνει email. Διορθώστε τον διακομιστή σας και πατήστε saveΑποθήκευση για να το ενεργοποιήσετε ξανά.
• Κατά καιρούς ένα συμβάν φτάνει δύο φορές ή εκτός σειράς. Χρησιμοποιήστε το id για να αγνοείτε τις επαναλήψεις και το created για να βάζετε τα συμβάντα στη σειρά.

Ελέγξτε την υπογραφή#

Όποιος γνωρίζει τη διεύθυνσή σας μπορεί να στείλει σε αυτήν, γι' αυτό ελέγχετε κάθε παράδοση πριν την εμπιστευτείτε:

1. Χωρίστε την κεφαλίδα X-MMO-Signature στο κόμμα σε t και v1.
2. Υπολογίστε ένα HMAC-SHA256 του t, μιας τελείας και του ακατέργαστου σώματος του αιτήματος, με κλειδί το signing secret σας, γραμμένο σε δεκαεξαδική μορφή.
3. Συγκρίνετε το αποτέλεσμα με το v1 με σύγκριση σταθερού χρόνου.
4. Απορρίψτε την παράδοση αν το t απέχει περισσότερο από 5 λεπτά από την τρέχουσα ώρα. Το t είναι σε χιλιοστά του δευτερολέπτου.

Χρησιμοποιήστε το σώμα ακριβώς όπως έφτασε: αν αναλύσετε το JSON και το γράψετε ξανά, αλλάζει και η υπογραφή δεν ταιριάζει πια.

Το autorenewΑνανέωση secret αντικαθιστά αμέσως το secret και δείχνει το νέο ολόκληρο, μία φορά. Ενημερώστε τον διακομιστή σας αμέσως μόλις το αλλάξετε.

Συμβάντα#