Der HTTPS-Endpunkt von Amazon Neptune OpenCypher - Amazon Neptune
Lese- und SchreibabfragenOpenCypher ErgebnisformatOptionale HTTP-Trailing-Header

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Der HTTPS-Endpunkt von Amazon Neptune OpenCypher

OpenCypher Lese- und Schreibabfragen auf dem HTTPS-Endpunkt

Der OpenCypher HTTPS-Endpunkt unterstützt Lese- und Aktualisierungsabfragen, die GET sowohl die als auch die POST Methode verwenden. Die Methoden DELETE und PUT werden nicht unterstützt.

In den folgenden Anweisungen erfahren Sie, wie Sie mithilfe des curl Befehls und HTTPS eine Verbindung zum OpenCypher Endpunkt herstellen. Sie müssen diesen Anweisungen von einer EC2 Amazon-Instance aus folgen, die sich in derselben Virtual Private Cloud (VPC) wie Ihre Neptune-DB-Instance befindet.

Die Syntax lautet wie folgt:

HTTPS://(the server):(the port number)/openCypher

Dies sind Beispiele für Leseabfragen. Eine Abfrage verwendet POST und eine Abfrage verwendet GET:

1. Verwenden von POST:

curl HTTPS://server:port/openCypher \
  -d "query=MATCH (n1) RETURN n1;"

2. Verwenden von GET (die Abfragezeichenfolge ist URL-codiert):

curl -X GET \
  "HTTPS://server:port/openCypher?query=MATCH%20(n1)%20RETURN%20n1"

Hier sind write/update Beispielabfragen, eine, die verwendet, POST und eine, die Folgendes verwendet: GET

1. Verwenden von POST:

curl HTTPS://server:port/openCypher \
  -d "query=CREATE (n:Person { age: 25 })"

2. Verwenden von GET (die Abfragezeichenfolge ist URL-codiert):

curl -X GET \
  "HTTPS://server:port/openCypher?query=CREATE%20(n%3APerson%20%7B%20age%3A%2025%20%7D)"

Das standardmäßige OpenCypher JSON-Ergebnisformat

Das folgende JSON-Format wird entweder standardmäßig oder durch explizites Festlegen des Anforderungs-Headers auf Accept: application/json zurückgegeben. Dieses Format soll mithilfe nativer Features der meisten Bibliotheken leicht in Objekte geparst werden können.

Das zurückgegebene JSON-Dokument enthält ein einzelnes Feld (results), das die Abfragerückgabewerte enthält. Die folgenden Beispiele zeigen die JSON-Formatierung häufiger Werte.

Beispiel für eine Wertantwort:

{
  "results": [
    {
      "count(a)": 121
    }
  ]
}

Beispiel für eine Knotenantwort:

{
  "results": [
    {
      "a": {
        "~id": "22",
        "~entityType": "node",
        "~labels": [
          "airport"
        ],
        "~properties": {
          "desc": "Seattle-Tacoma",
          "lon": -122.30899810791,
          "runways": 3,
          "type": "airport",
          "country": "US",
          "region": "US-WA",
          "lat": 47.4490013122559,
          "elev": 432,
          "city": "Seattle",
          "icao": "KSEA",
          "code": "SEA",
          "longest": 11901
        }
      }
    }
  ]
}

Beispiel für eine Beziehungsantwort:

{
  "results": [
    {
      "r": {
        "~id": "7389",
        "~entityType": "relationship",
        "~start": "22",
        "~end": "151",
        "~type": "route",
        "~properties": {
          "dist": 956
        }
      }
    }
  ]
}

Beispiel für eine Pfadantwort:

{
  "results": [
    {
      "p": [
        {
          "~id": "22",
          "~entityType": "node",
          "~labels": [
            "airport"
          ],
          "~properties": {
            "desc": "Seattle-Tacoma",
            "lon": -122.30899810791,
            "runways": 3,
            "type": "airport",
            "country": "US",
            "region": "US-WA",
            "lat": 47.4490013122559,
            "elev": 432,
            "city": "Seattle",
            "icao": "KSEA",
            "code": "SEA",
            "longest": 11901
          }
        },
        {
          "~id": "7389",
          "~entityType": "relationship",
          "~start": "22",
          "~end": "151",
          "~type": "route",
          "~properties": {
            "dist": 956
          }
        },
        {
          "~id": "151",
          "~entityType": "node",
          "~labels": [
            "airport"
          ],
          "~properties": {
            "desc": "Ontario International Airport",
            "lon": -117.600997924805,
            "runways": 2,
            "type": "airport",
            "country": "US",
            "region": "US-CA",
            "lat": 34.0559997558594,
            "elev": 944,
            "city": "Ontario",
            "icao": "KONT",
            "code": "ONT",
            "longest": 12198
          }
        }
      ]
    }
  ]
}

Optionale HTTP-Header am Ende für mehrteilige Antworten OpenCypher

Diese Funktion ist ab Version 1.4.5.0 der Neptune Engine verfügbar.

Die HTTP-Antwort auf OpenCypher Abfragen und Aktualisierungen wird in der Regel in mehreren Abschnitten zurückgegeben. Wenn nach dem Senden der ersten Antwort-Chunks (mit dem HTTP-Statuscode 200) Fehler auftreten, kann es schwierig sein, das Problem zu diagnostizieren. Standardmäßig meldet `Neptune solche Fehler, indem es eine Fehlermeldung an den Nachrichtentext anhängt, der aufgrund des Streaming-Charakters der Antwort beschädigt sein kann.

Verwenden von abschließenden Headern

Um die Fehlererkennung und -diagnose zu verbessern, können Sie Trailing-Header aktivieren, indem Sie Ihrer Anfrage einen Trailer-Header (TE: Trailers) für Transfer-Encoding (TE) hinzufügen. Anschließend fügt Neptune zwei neue Header-Felder in die Trailing-Header der Antwortblöcke ein:

  • X-Neptune-Status— enthält den Antwortcode gefolgt von einem Kurznamen. Im Erfolgsfall wäre der nachgestellte Header beispielsweise: X-Neptune-Status: 200 OK. Im Fehlerfall wäre der Antwortcode ein Neptune-Engine-Fehlercode wie. X-Neptune-Status: 500 TimeLimitExceededException

  • X-Neptune-Detail— ist bei erfolgreichen Anfragen leer. Im Fehlerfall ist die JSON-Fehlermeldung enthalten. Da in HTTP-Header-Werten nur ASCII-Zeichen zulässig sind, ist die JSON-Zeichenfolge URL-codiert. Die Fehlermeldung wird weiter an die Antwortmeldung angefügt.

Weitere Informationen finden Sie auf der MDN-Seite zu TE-Anforderungsheadern.

OpenCypher Beispiel für die Verwendung von Trailing-Headern

Dieses Beispiel zeigt, wie abschließende Header bei der Diagnose einer Abfrage helfen, deren Zeitlimit überschritten wird: 

curl --raw 'https://your-neptune-endpoint:port/openCypher' \
-H 'TE: trailers' \
-d 'query=MATCH(n) RETURN n.firstName'
 
 
Output:
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< trailer: X-Neptune-Status, X-Neptune-Detail
< content-type: application/json;charset=UTF-8
< 
< 
{
  "results": [{
      "n.firstName": "Hossein"
    }, {
      "n.firstName": "Jan"
    }, {
      "n.firstName": "Miguel"
    }, {
      "n.firstName": "Eric"
    }, 
{"detailedMessage":"Operation terminated (deadline exceeded)",
"code":"TimeLimitExceededException",
"requestId":"a7e9d2aa-fbb7-486e-8447-2ef2a8544080",
"message":"Operation terminated (deadline exceeded)"}
0
X-Neptune-Status: 500 TimeLimitExceededException
X-Neptune-Detail: %7B%22detailedMessage%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%2C%22code%22%3A%22TimeLimitExceededException%22%2C%22requestId%22%3A%22a7e9d2aa-fbb7-486e-8447-2ef2a8544080%22%2C%22message%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%7D
Aufschlüsselung der Antworten:

Das vorherige Beispiel zeigt, wie eine OpenCypher Antwort mit abschließenden Headern bei der Diagnose von Abfragefehlern helfen kann. Hier sehen wir vier aufeinanderfolgende Teile: (1) anfängliche Header mit einem Status von 200 OK, der anzeigt, dass das Streaming beginnt, (2) teilweise (fehlerhafte) JSON-Ergebnisse, die vor dem Ausfall erfolgreich gestreamt wurden, (3) die angefügte Fehlermeldung mit dem Timeout und (4) nachfolgende Header, die den endgültigen Status (500) und detaillierte Fehlerinformationen enthalten. TimeLimitExceededException