Messungen über die MetriX REST-Schnittstelle

Inhalte:

1. Auslösen von Messungen über die REST-Schnittstelle

2. Erklärungen zu verschiedene HTTP-Responses

---

Auslösen von Messungen über die REST-Schnittstelle

MetriX stellt eine REST-Schnittstelle zur Verfügung, über die Messungen ausgelöst werden können. Standardmäßig erfolgt der Zugriff über Port 32321.
Die entsprechende Route lautet: /measurement/1234.

(Dabei steht 1234 exemplarisch für einen eindeutigen von Ihnen definierten Identifikator, z. B. einen Barcode, eine PieceID, etc..)

• Die Route kann sowohl per HTTP POST als auch per HTTP GET angesprochen werden. 
• Der Header sollte dabei immer den Content-Type: application/json enthalten.
• Wenn Sie zusätzliche Informationen zur Messung übermitteln möchten, kann der Request einen beliebigen JSON-Body enthalten. 

{
   "foo": 42,
   "bar": "abc"
}

 

Bitte beachten Sie: Ein JSON-Body ist auch mit GET möglich (siehe RFC2616), wobei ältere HTTP Clients dies nicht unterstützen.

 

---

 

Erklärungen zu verschiedenen HTTP-Responses

Sie können MetriX sowohl eine HTTP POST Request, als auch HTTP GET Request schicken:

• HTTP POST Request an MetriX
  Das System wird angewiesen, eine Messung für den übermittelten Identifikator durchzuführen. Das Messergebnis wird dabei nicht zurückgeliefert.
• HTTP GET Request an MetriX
  Das System wird angewiesen, eine Messung zum übermittelten Identifikator durchzuführen und das Ergebnis direkt zurück zuliefern.

Nachfolgend sind die möglichen Responses aufgeführt:

✅ POST | 200 OK

Antwortet MetriX mit 200 OK, wurde der Identifikator erfolgreich akzeptiert und das System befindet sich in einem Zustand, in dem eine Messung möglich ist.

✅ GET | 200 OK

Sind alle Voraussetzungen erfüllt, antwortet MetriX wie folgend im exemplarischen Response-Body:

{
  "id": "TestSystem20250606110729846",
  "systemId": "TestSystem",
  "timestamp": "2025-06-06T11:07:58.7589839Z",
  "dimensioningState": "Stable",
  "legalForTradeHash": "956356C986A3574C3D61E98913159796",
  "length": 1.22,
  "width": 0.8,
  "height": 1.92,
  "exactVolume": 1.37392,
  "weight": 98,
  "weightState": "Stable",
  "weightReference": "0815",
  "images": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "overlayImages": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "croppedImages": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "croppedOverlayImages": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...j5GRd2JDjgVmZmMZ/9k="
  ],
  "userData": {
    "externalIdentifiers": [
      "1234"
    ],
    "payload": {
      "foo": 42,
      "bar": "abc"
    },
    "length": 1.2,
    "width": 0.8,
    "height": null,
    "weight": null,
    "customFields": {
      "isSeaFreight": true
    }
  }
}

Ausführliche Erklärungen zu den aufgeführten Eigenschaften:

Alle Werte sind grundsätzlich in SI-Einheiten (Meter, Kilogramm bzw. Kubikmeter) angegeben. Davon ausgenommen sind manuell eingegebene Werte in der Eigenschaft userData, die ggf. kundenspezifische Einheiten haben.

Die Bilder werden als Data Url übertragen.

Bitte beachten Sie: Ein System kann mehrere Farbkameras haben. Innerhalb eines System können Bilder in unterschiedliche Auflösungen aufgenommen und gespeichert werden. Je nach Konfiguration kann es sein, dass nicht alle Bilder ausgegeben werden (z. B. um Größe der Antwort zu reduzieren). Der Content-Type der Bilder sollte berücksichtigt werden. 

❌ POST/GET | 400 Bad Request

Wird der Identifikator nicht akzeptiert oder befindet sich das System in einem Zustand, der keine Messungen erlaubt, erhalten Sie die Response: 400 Bad Request. Welches Problem vorliegt, erfahren Sie im Response-Body (siehe RFC7807).

Mögliche Fehlermeldungen und was sie bedeuten:

• • • Invalid Identifier

Während der Konfiguration Ihres MetriX-Systems werden definierten Identifikatoren, bestimmte Formate hinterlegt. Erhält MetriX nun einen Identifikator, dessen Format vom hinterlegten abweicht, erscheint folgende Antwort:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The external identifier does not match the configured format and is ignored.",
  "instance": "measurement/bar@@",
  "traceId": "0HND4SS6QTH5U:00000001"
}

 

• • • Additional Identifier disabled 

Bei individuell konfigurierten Spezialsystemen von MetriX ist es möglich, mehrere Identifikatoren einer Messung zuzuordnen. Wird diese Einstellung im entsprechenden System deaktiviert und das System erhält neben dem Standard Identifikator weitere Werte, erscheint folgende Antwort:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Additional external identifiers are disabled and the identifier is ignored.",
  "instance": "measurement/bar",
  "traceId": "0HND4T17Q41R8:00000002"
}

 

• • • Verification required

Wenn das System verifiziert werden muss, bevor die nächste Messung durchgeführt werden kann, erscheint folgende Antwort:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The external identifier is ignored due to pending verification.",
  "instance": "measurement/bar",
  "traceId": "0HND4T2NA1KJ0:00000001"
}

❌ GET | 404 Not Found 

Wenn MetriX keine Messung durchführen, weil z. B. der Messbereich leer oder das Gewicht nicht stabil ist, dann antwortet das System nach einem Timeout mit dem entsprechenden HTTP-Code: 404 Not Found. 

 

---

 

Möchten Sie die Implementierung im Vorfeld ausprobieren? 

Kein Problem, Ihnen steht eine öffentlich zugängliche Test-REST-Schnittstelle zur Verfügung. Die Test-Schnittstelle bildet das Verhalten des echten Systems weitgehend ab. Trotzdem kann es zu vereinzelten Einschränkungen bzw. Besonderheiten kommen.

Direkt zum ausführlichen Artikel Technische Informationen zur Test-Schnittstelle