As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# O endpoint HTTPS do Amazon OpenCypher Neptune
<a name="access-graph-opencypher-queries"></a>

**Topics**
+ [OpenCypher consultas de leitura e gravação no endpoint HTTPS](#access-graph-opencypher-queries-read-write)
+ [O formato padrão de resultados OpenCypher JSON](#access-graph-opencypher-queries-results-simple-JSON)
+ [Cabeçalhos finais HTTP opcionais para respostas em várias partes OpenCypher](#optional-http-trailing-headers)

**nota**  
Atualmente, o Neptune não oferece HTTP/2 suporte a solicitações da API REST. Os clientes devem usar HTTP/1.1 ao se conectar aos endpoints.

## OpenCypher consultas de leitura e gravação no endpoint HTTPS
<a name="access-graph-opencypher-queries-read-write"></a>

O endpoint OpenCypher HTTPS oferece suporte a consultas de leitura e atualização usando o método `GET` e o`POST`. Os métodos `DELETE` e `PUT` não são compatíveis.

As instruções a seguir orientam você na conexão com o OpenCypher endpoint usando o `curl` comando e HTTPS. Você deve seguir estas instruções em uma instância do Amazon EC2 na mesma nuvem privada virtual (VPC) que a instância de banco de dados do Neptune.

A sintaxe é:

```
HTTPS://{{(the server)}}:{{(the port number)}}/openCypher
```

Aqui está um exemplo de consulta de leitura:

------
#### [ AWS CLI ]

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

Para obter mais informações, consulte [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) na Referência de Comandos. 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'])
```

Para exemplos de AWS SDK em outras linguagens, consulte[AWS SDK](access-graph-opencypher-sdk.md).

------
#### [ awscurl ]

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

**nota**  
Este exemplo pressupõe que suas AWS credenciais estejam configuradas em seu ambiente. {{us-east-1}}Substitua pela região do seu cluster Neptune.

------
#### [ curl ]

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

------

Aqui está um exemplo de write/update consulta:

------
#### [ AWS CLI ]

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

Para obter mais informações, consulte [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) na Referência de Comandos. 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'])
```

Para exemplos de AWS SDK em outras linguagens, consulte[AWS SDK](access-graph-opencypher-sdk.md).

------
#### [ 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**  
Este exemplo pressupõe que suas AWS credenciais estejam configuradas em seu ambiente. {{us-east-1}}Substitua pela região do seu cluster Neptune.

------
#### [ curl ]

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

------

## O formato padrão de resultados OpenCypher JSON
<a name="access-graph-opencypher-queries-results-simple-JSON"></a>

O formato JSON a seguir é gerado por padrão ou definindo explicitamente o cabeçalho de solicitação como `Accept: application/json`. Esse formato foi projetado para ser facilmente analisado em objetos usando atributos de linguagem nativa da maioria das bibliotecas.

O documento JSON gerado apresenta um campo, `results`, que contém os valores de retorno da consulta. Os exemplos abaixo mostram a formatação JSON para valores comuns.

**Exemplo de resposta de valor:**

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

**Exemplo de resposta do nó:**

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

**Exemplo de resposta de relacionamento:**

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

**Exemplo de resposta de caminho:**

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

## Cabeçalhos finais HTTP opcionais para respostas em várias partes OpenCypher
<a name="optional-http-trailing-headers"></a>

 Esse recurso está disponível a partir da versão [1.4.5.0](https://docs.aws.amazon.com/releases/release-1.4.5.0.xml) do mecanismo do Neptune. 

 A resposta HTTP às OpenCypher consultas e atualizações geralmente é retornada em vários blocos. Quando ocorrem falhas após o envio dos fragmentos de resposta inicial (com um código de status HTTP de 200), pode ser difícil diagnosticar o problema. Por padrão, o Neptune relata essas falhas anexando uma mensagem de erro ao corpo da mensagem, que pode estar corrompida devido à natureza de streaming da resposta. 

**Usar cabeçalhos finais**  
 Para melhorar a detecção e o diagnóstico de erros, habilite os cabeçalhos finais incluindo um cabeçalho final de transferência de codificação (TE) (te: trailers) na solicitação. Isso fará com que o Neptune inclua dois novos campos de cabeçalho nos cabeçalhos finais dos blocos de resposta: 
+  `X-Neptune-Status`: contém o código de resposta seguido por um nome curto. Por exemplo, em caso de êxito, o cabeçalho final seria: `X-Neptune-Status: 200 OK`. Em caso de falha, o código de resposta seria um código de erro do mecanismo do Neptune, como `X-Neptune-Status: 500 TimeLimitExceededException`. 
+  `X-Neptune-Detail`: fica em branco para solicitações bem-sucedidas. No caso de erros, ele contém a mensagem de erro JSON. Como somente caracteres ASCII são permitidos nos valores do cabeçalho HTTP, a string JSON é codificada em URL. A mensagem de erro também ainda é anexada ao corpo da mensagem de resposta. 

 Para obter mais informações, consulte a [página MDN sobre cabeçalhos de solicitação TE](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/TE). 

**OpenCypher exemplo de uso de cabeçalhos à direita**  
 Este exemplo demonstra como os cabeçalhos finais ajudam a diagnosticar uma consulta que excede seu limite de 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
```

**Detalhamento de respostas:**  
 O exemplo anterior mostra como uma OpenCypher resposta com cabeçalhos à direita pode ajudar a diagnosticar falhas na consulta. Aqui vemos quatro partes sequenciais: (1) cabeçalhos iniciais com um status 200 OK indicando o início do streaming, (2) resultados JSON parciais (interrompidos) transmitidos com sucesso antes da falha, (3) a mensagem de erro anexada mostrando o tempo limite e (4) cabeçalhos finais contendo o status final (500) e informações detalhadas do erro. TimeLimitExceededException