L'endpoint HTTPS di Amazon OpenCypher Neptune - Amazon Neptune
Query di lettura e scritturaOpenCypher formato dei risultatiIntestazioni HTTP finali opzionali

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

L'endpoint HTTPS di Amazon OpenCypher Neptune

OpenCypher query di lettura e scrittura sull'endpoint HTTPS

L'endpoint OpenCypher HTTPS supporta le query di lettura e aggiornamento utilizzando sia il metodo che ilGET. POST I metodi DELETE e PUT non sono supportati.

Le seguenti istruzioni illustrano la connessione all' OpenCypher endpoint utilizzando il curl comando e HTTPS. È necessario seguire queste istruzioni da un' EC2 istanza Amazon nello stesso cloud privato virtuale (VPC) dell'istanza Neptune DB.

La sintassi è:

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

Ecco alcune query di lettura di esempio, una che utilizza POST e una che utilizza GET:

1. Con POST:

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

2. Con GET (la stringa di query è codificata come URL):

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

Ecco alcuni esempi di write/update query, una che utilizza POST e l'altra che utilizza: GET

1. Con POST:

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

2. Con GET (la stringa di query è codificata come URL):

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

Il formato dei risultati OpenCypher JSON predefinito

Il seguente formato JSON viene restituito per impostazione predefinita o impostando l'intestazione della richiesta in modo esplicito su Accept: application/json. Questo formato è stato progettato per essere facilmente analizzato in oggetti utilizzando le funzionalità del linguaggio nativo della maggior parte delle librerie.

Il documento JSON restituito contiene un campo, results, che contiene i valori restituiti dalla query. Gli esempi seguenti mostrano la formattazione JSON per i valori comuni.

Esempio di risposta di valore:

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

Esempio di risposta di nodo:

{
  "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
        }
      }
    }
  ]
}

Esempio di risposta di relazione:

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

Esempio di risposta di percorso:

{
  "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
          }
        }
      ]
    }
  ]
}

Intestazioni finali HTTP opzionali per risposte in più parti OpenCypher

Questa funzionalità è disponibile a partire dalla versione 1.4.5.0 del motore Neptune.

La risposta HTTP alle OpenCypher domande e agli aggiornamenti viene in genere restituita in più blocchi. Quando si verificano errori dopo l'invio dei blocchi di risposta iniziali (con un codice di stato HTTP di 200), può essere difficile diagnosticare il problema. Per impostazione predefinita, `Neptune segnala tali errori aggiungendo un messaggio di errore al corpo del messaggio, che potrebbe essere danneggiato a causa della natura di streaming della risposta.

Usare le intestazioni finali

Per migliorare il rilevamento e la diagnosi degli errori, puoi abilitare le intestazioni finali includendo un'intestazione trailers (te: trailers) con codifica di trasferimento (TE) nella richiesta. In questo modo Neptune includerà due nuovi campi di intestazione nelle intestazioni finali dei blocchi di risposta:

  • X-Neptune-Status— contiene il codice di risposta seguito da un nome breve. Ad esempio, in caso di esito positivo, l'intestazione finale sarà: X-Neptune-Status: 200 OK. In caso di errore, il codice di risposta sarebbe un codice di errore del motore Neptune come. X-Neptune-Status: 500 TimeLimitExceededException

  • X-Neptune-Detail— è vuoto per le richieste andate a buon fine. In caso di errori, contiene il messaggio di errore JSON. Poiché nei valori di intestazione HTTP sono consentiti solo caratteri ASCII, la stringa JSON è codificata come URL. Inoltre, al corpo del messaggio di risposta viene anche aggiunto il messaggio di errore.

Per ulteriori informazioni, consulta la pagina MDN sulle intestazioni delle richieste TE.

OpenCypher esempio di utilizzo delle intestazioni finali

Questo esempio dimostra come le intestazioni finali aiutano a diagnosticare una query che supera il limite di tempo: 

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
Suddivisione della risposta:

L'esempio precedente mostra come una OpenCypher risposta con intestazioni finali può aiutare a diagnosticare gli errori delle query. Qui vediamo quattro parti sequenziali: (1) intestazioni iniziali con stato 200 OK che indica l'inizio dello streaming, (2) risultati JSON parziali (interrotti) trasmessi correttamente prima dell'errore, (3) il messaggio di errore aggiunto che mostra il timeout e (4) le intestazioni finali contenenti lo stato finale (500) e informazioni dettagliate sull'errore. TimeLimitExceededException