View a markdown version of this page

Le point de terminaison OpenCypher HTTPS d'Amazon Neptune - Amazon Neptune
Requêtes de lecture et d'écritureOpenCypher format des résultatsEn-têtes de suivi HTTP facultatifs

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Le point de terminaison OpenCypher HTTPS d'Amazon Neptune

Note

Neptune ne prend pas actuellement en charge HTTP/2 les requêtes d'API REST. Les clients doivent l'utiliser HTTP/1.1 lors de la connexion aux terminaux.

OpenCypher requêtes de lecture et d'écriture sur le point de terminaison HTTPS

Le point de terminaison OpenCypher HTTPS prend en charge les requêtes de lecture et de mise à jour à l'aide de la méthode GET et de la POST méthode. Les méthodes DELETE et PUT ne sont pas prises en charge.

Les instructions suivantes vous indiquent comment vous connecter au OpenCypher terminal à l'aide de la curl commande et du protocole HTTPS. Vous devez suivre ces instructions à partir d'une instance Amazon EC2 dans le même cloud privé virtuel (VPC) (VPC) que l'instance de base de données Neptune.

La syntaxe est la suivante :

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

Voici un exemple de requête de lecture :

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

Pour plus d'informations, consultez https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html execute-open-cypher-query dans la référence des commandes. 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'])

Pour des exemples de AWS SDK dans d'autres langues, consultezAWS SDK.

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

Cet exemple suppose que vos AWS informations d'identification sont configurées dans votre environnement. us-east-1Remplacez-la par la région de votre amas Neptune.

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

Voici un exemple de write/update requête :

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

Pour plus d'informations, consultez https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html execute-open-cypher-query dans la référence des commandes. 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'])

Pour des exemples de AWS SDK dans d'autres langues, consultezAWS 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 })"
Note

Cet exemple suppose que vos AWS informations d'identification sont configurées dans votre environnement. us-east-1Remplacez-la par la région de votre amas Neptune.

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

Le format de résultats OpenCypher JSON par défaut

Le format JSON suivant est renvoyé par défaut ou en définissant explicitement l'en-tête de demande sur Accept: application/json. Ce format est conçu pour être facilement analysé en objets à l'aide des fonctionnalités du langage natif de la plupart des bibliothèques.

Le document JSON renvoyé contient un champ, results, qui comporte les valeurs renvoyées par la requête. Les exemples ci-dessous montrent la mise en forme JSON pour les valeurs courantes.

Exemple de réponse pour une valeur :

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

Exemple de réponse pour un nœud :

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

Exemple de réponse pour une relation :

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

Exemple de réponse pour un chemin :

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

En-têtes HTTP de fin facultatifs pour les réponses en plusieurs parties OpenCypher

Cette fonctionnalité est disponible à partir de la version https://docs.aws.amazon.com/releases/release-1.4.5.0.xml 1.4.5.0 du moteur Neptune.

La réponse HTTP aux OpenCypher requêtes et aux mises à jour est généralement renvoyée en plusieurs segments. Lorsque des échecs surviennent après l'envoi des premiers segments de réponse (avec un code d'état HTTP de 200), il peut être difficile de diagnostiquer le problème. Par défaut, `Neptune signale ces échecs en ajoutant un message d'erreur au corps du message, qui peut être endommagé en raison de la nature de la réponse en streaming.

Utilisation d'en-têtes de fin

Pour améliorer la détection et le diagnostic des erreurs, vous pouvez activer les en-têtes de fin en incluant un en-tête de bandes-annonces à codage par transfert (TE : trailers) dans votre demande. De cette manière, Neptune inclura deux nouveaux champs d'en-tête dans les en-têtes de suivi des fragments de réponse :

  • X-Neptune-Status— contient le code de réponse suivi d'un nom abrégé. Par exemple, en cas de réussite, l'en-tête final serait : X-Neptune-Status: 200 OK. En cas de panne, le code de réponse serait un code d'erreur du moteur Neptune tel queX-Neptune-Status: 500 TimeLimitExceededException.

  • X-Neptune-Detail— est vide pour les demandes réussies. En cas d'erreur, il contient le message d'erreur JSON. Étant donné que seuls les caractères ASCII sont autorisés dans les valeurs d'en-tête HTTP, la chaîne JSON est encodée en URL. Le message d'erreur est également toujours ajouté au corps du message de réponse.

Pour plus d'informations, consultez la page MDN sur les en-têtes de requête TE.

OpenCypher exemple d'utilisation des en-têtes de fin

Cet exemple montre comment les en-têtes de fin permettent de diagnostiquer une requête qui dépasse sa limite de temps : 

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
Répartition des réponses :

L'exemple précédent montre comment une OpenCypher réponse avec des en-têtes de fin peut aider à diagnostiquer les échecs des requêtes. Nous voyons ici quatre parties séquentielles : (1) les en-têtes initiaux avec un statut 200 OK indiquant le début du streaming, (2) les résultats JSON partiels (cassés) diffusés avec succès avant l'échec, (3) le message d'erreur joint indiquant le délai d'attente, et (4) les en-têtes de fin contenant l'état final (500) et des informations d'erreur détaillées. TimeLimitExceededException