View a markdown version of this page

L'endpoint HTTPS di Amazon Neptune OpenCypher - 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 Neptune OpenCypher

Nota

Neptune attualmente non supporta le richieste API REST. HTTP/2 I client devono HTTP/1.1 utilizzarlo per connettersi agli endpoint.

OpenCypher leggere e scrivere query sull'endpoint HTTPS

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

Le seguenti istruzioni illustrano la procedura di 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 https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html execute-open-cypher-query nel Command Reference. AWS CLI

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 di AWS SDK in altre lingue, consulta. AWS 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 tue AWS credenziali siano configurate nel tuo 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 interrogazione:

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 https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html execute-open-cypher-query nel Command Reference. AWS CLI

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 di AWS SDK in altre lingue, consulta. AWS 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 tue AWS credenziali siano configurate nel tuo 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
          }
        }
      ]
    }
  ]
}

Header finali HTTP opzionali per risposte composte da più parti OpenCypher

Questa funzionalità è disponibile a partire dalla versione 1.4.5.0 del motore Neptune. https://docs.aws.amazon.com/releases/release-1.4.5.0.xml

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 200), può essere difficile diagnosticare il problema. Per impostazione predefinita, `Neptune segnala tali errori aggiungendo un messaggio di errore nel 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 transfer-encoding (TE) (te: trailers) nella tua 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, ad esempio. X-Neptune-Status: 500 TimeLimitExceededException

  • X-Neptune-Detail— è vuoto se le richieste sono 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 aiutino 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 delle risposte:

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 uno stato 200 OK che indica l'inizio dello streaming, (2) risultati JSON parziali (interrotti) trasmessi correttamente in streaming prima dell'errore, (3) il messaggio di errore aggiunto che mostra il timeout e (4) intestazioni finali contenenti lo stato finale (500) e informazioni dettagliate sull'errore. TimeLimitExceededException