Table of Contents

Einführung in die Cloud-Recognition-APIs

Api übersicht

Rest-api-schnittstellenprotokoll und authentifizierungsmechanismus

CRS-API folgt dem Standard-HTTP-REST-Übertragungsstandard.

Http-Header

    Authorization: <Token aus dem ApiKey einfügen>

Http-Anforderungsparameter werden in zwei Typen unterteilt:

  • Gemeinsame Parameter (insgesamt diese, unterschiedliche Kombinationen bei unterschiedlicher Authentifizierung):

    • appId
    • timestamp (Long-Ganzzahl: Millisekunden seit 1. Januar 1970, 00:00:00 UTC)
    • apiKey
    • signature (Anforderungssignatur, bei Token-Authentifizierung alternativ)

  • CRS-API-Parameter: Eigene Parameter der API

    Authentifizierungsparameter werden in der API-Dokumentation nicht beschrieben

Api-key-authentifizierung

Die Authentifizierung erfolgt auf zwei Arten:

Token-basierte Authentifizierung

Http-Header Authorization enthält Token, gemeinsame Parameter umfassen:

  • appId

Signatur-Authentifizierung

Kein Http-Header Authorization.

Gemeinsame Parameter enthalten Signaturinformationen. Alle Parameter (außer Bildern) werden in die Signaturberechnung einbezogen.

  • appId
  • timestamp
  • apiKey
  • signature

Detaillierte Algorithmen und Code zur Signaturberechnung finden Sie im Dokument Api-Key-Signaturmethode.

Verwendungsbeispiele und eigenschaftsanalyse

Api-verwendungsbeispiel

Hier veranschaulicht ein Beispiel – der Aufruf der API-Schnittstelle zum Erstellen eines Zielbildes – den CRS-API-Anfrageprozess für Entwickler, zeigt die Eigenschaftenstruktur des Zielbildes sowie die Ein- und Ausgabe der Schnittstelle.

In der Produktionsumgebung sind vor dem Erstellen eines Zielbildes weitere Validierungen erforderlich. Befolgen Sie die Best Practices, um ein neues Zielbild zu erstellen.

Anfragebeispiel

Fügen Sie eine neue Zielbilddatei test-target.jpg hinzu. Beim Erstellen muss die Bilddatei Base64-kodiert sein.

Die API-Dokumentation erläutert die Anforderungsparameter detailliert. Siehe API – Zielbild erstellen, Base64-kodierte Bilddatei anfordern.

POST /targets HTTP/1.1
Host:
Date: Mon, 1 Jan 2018 00:00:00 GMT
Content-Type: application/json
{
    "image":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM...",
    "active":"1",
    "name":"easyar",
    "size":"5",
    "meta":"496fbbabc2b38ecs3460a...",
    "type":"ImageTarget",
    "timestamp": 1514736000000,
    "apiKey": "8b485c648c3056e79c2a85ee9b51f9dc",
    "appId": "C:CN1:f9f903c36da8bd64d71d491077bba...",
    "signature": "89985e2420899196db5bdf16b3c2ed0922c0c221"
}

Antwortbeispiel

HTTP/1.1 200 OK
Content-Type: application/json
{
    "statusCode": 0,
    "result": {
        "targetId":"e61db301-e80f-4025-b822-9a00eb48d8d2",
        "trackingImage":"/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAMCAgM..."，
        "name": "easyar",
        "size": "5",
        "meta": "496fbbabc2b38ecs3460a...",
        "type": "ImageTarget",
        "modified":1514735000000
        "active":"1"，
        "trackableRate": 0,
        "detectableRate": 0,
        “detectableDistinctiveness”：0,
        "detectableFeatureCount": 0,
        "trackableDistinctiveness": 0,
        "trackableFeatureCount": 0,
        "trackableFeatureDistribution": 0,
        "trackablePatchContrast": 0,
        "trackablePatchAmbiguity": 0
    },
    "timestamp": 1514736000000
}

Antwortformat

Antworten verwenden ein einheitliches Format. Hier ist ein Beispiel:

{
  "statusCode": 119,
  "msg": "Parameter has errors",
  "date": "2022-06-15T09:56:30.000Z",
  "result":  //result ist nur vorhanden, wenn statusCode 0 ist. Bei Fehlern ist das Feld leer
}

Wie im obigen Beispiel zeigt diese Struktur die Details eines normal zurückgegebenen Zielbildes. Ein Zielbild umfasst folgende Attribute

Attribut Beschreibung
targetId Eindeutige ID des Zielbildes
trackingImage Base64-kodiertes Graustufenbild für das Gerätetracking
name Name des Zielbildes
size Bildgröße, tatsächliche Größe für das Overlay virtueller Inhalte
meta Benutzerbezogene Daten (Datei, Text oder URL), Base64-kodiert
type "ImageTarget"
active Nur aktivierte Zielbilder sind erkennbar
trackableRate Tracking-Schwierigkeitsbewertung, kleiner ist besser
detectableRate Erkennungsschwierigkeitsbewertung, kleiner ist besser
detectableDistinctiveness Erkennungsunterscheidungsschwierigkeit, kleiner ist besser
detectableFeatureCount Erkennungsmerkmal-Schwierigkeitsbewertung, kleiner ist besser
trackableDistinctiveness Tracking-Unterscheidungsschwierigkeit, kleiner ist besser
trackableFeatureCount Tracking-Merkmal-Schwierigkeitsbewertung, kleiner ist besser
trackableFeatureDistribution Tracking-Merkmalverteilungs-Schwierigkeit, kleiner ist besser

Fehlercodes

Erklärung der Cloud-Recognition-API-Fehlercodes

Verwandte Themen