View a markdown version of this page

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

Nota

Neptune attualmente non supporta HTTP/2 per le richieste API REST. I client devono utilizzare HTTP/1.1 per la connessione agli endpoint.

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. Segui queste istruzioni da un'istanza Amazon EC2 nello stesso cloud privato virtuale (VPC) dell'istanza database Neptune.

La sintassi è:

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

Ecco un esempio di query di lettura:

AWS CLI
aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "MATCH (n1) RETURN n1"

Per ulteriori informazioni, vedere execute-open-cypher-querynel AWS CLI Command Reference.

SDK
import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='MATCH (n1) RETURN n1'
)

print(response['results'])

Per esempi AWS SDK in altre lingue, consultaAWS SDK.

awscurl
awscurl https://your-neptune-endpoint:port/openCypher \
  --region us-east-1 \
  --service neptune-db \
  -X POST \
  -d "query=MATCH (n1) RETURN n1"
Nota

Questo esempio presuppone che le AWS credenziali siano configurate nel proprio ambiente. Sostituisci us-east-1 con la regione del tuo cluster Neptune.

curl
curl https://your-neptune-endpoint:port/openCypher \
  -d "query=MATCH (n1) RETURN n1"

Ecco un esempio write/update di query:

AWS CLI
aws neptunedata execute-open-cypher-query \
  --endpoint-url https://your-neptune-endpoint:port \
  --open-cypher-query "CREATE (n:Person { age: 25 })"

Per ulteriori informazioni, vedere execute-open-cypher-querynel AWS CLI Command Reference.

SDK
import boto3
from botocore.config import Config

client = boto3.client(
    'neptunedata',
    endpoint_url='https://your-neptune-endpoint:port',
    config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)

response = client.execute_open_cypher_query(
    openCypherQuery='CREATE (n:Person { age: 25 })'
)

print(response['results'])

Per esempi AWS SDK in altre lingue, consultaAWS SDK.

awscurl
awscurl https://your-neptune-endpoint:port/openCypher \
  --region us-east-1 \
  --service neptune-db \
  -X POST \
  -d "query=CREATE (n:Person { age: 25 })"
Nota

Questo esempio presuppone che le AWS credenziali siano configurate nel proprio ambiente. Sostituisci us-east-1 con la regione del tuo cluster Neptune.

curl
curl https://your-neptune-endpoint:port/openCypher \
  -d "query=CREATE (n:Person { age: 25 })"

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