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à.
# Esportazione nativa per dati RDF
L'API di esportazione Neptune ti consente di esportare i dati dal tuo database Neptune in Amazon S3. Puoi esportare dati RDF in formato o. N-Triples N-Quads
## Come funziona l'esportazione nativa
L'esportazione nativa viene eseguita sull'istanza di scrittura del cluster Neptune e scrive i dati esportati su Amazon S3 utilizzando caricamenti in più parti. Poiché l'esportazione utilizza le risorse di calcolo dell'istanza writer, consigliamo vivamente di eseguire le esportazioni su un cluster clonato per evitare di influire sui carichi di lavoro di produzione. Per ulteriori informazioni, consulta [ Raccomandazioni. ](#neptune-native-export-recommendations)
### Produttività delle esportazioni
Il throughput di esportazione si ridimensiona in modo approssimativamente lineare con dimensioni dell'istanza fino a. `r7i.16xlarge` Come stima di pianificazione prudente, si prevedono circa ** 50.000 dichiarazioni al secondo per vCPU. **
Usa questa formula per stimare la durata dell'esportazione:
```
export_seconds = total_statements / (vCPUs × 50,000)
```
Il throughput effettivo dipende dalle caratteristiche del set di dati, tra cui la cardinalità dei predicati, la complessità delle istruzioni e la dimensione del cluster.
## Prerequisiti
Prima di utilizzare l'API di esportazione, devi:
+ Disporre di un cluster di database Neptune con versione 1.4.6.0 o successiva (versione 1.4.8.0 o successiva per il supporto) `exportFilter`
+ [Crea un ruolo IAM con le autorizzazioni per accedere al tuo bucket S3 ](#neptune-native-export-iam-s3)
+ [Associa il ruolo IAM al tuo cluster Neptune ](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-add-role-cluster.html)
+ [Configura un endpoint S3 VPC nel VPC del tuo cluster Neptune ](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-vpc.html)
## Raccomandazioni
[Consigliamo vivamente di eseguire l'operazione di esportazione su un cluster clonato senza carichi di lavoro per evitare l'impatto sulle prestazioni di produzione read/write . ](https://docs.aws.amazon.com/neptune/latest/userguide/manage-console-cloning.html)
Per un rapporto prezzo/prestazioni ottimale, consigliamo di utilizzare istanze ** 16xlarge ** per le operazioni di esportazione. Questo tipo di istanza fornisce:
+ Memoria sufficiente per gestire set di dati di grandi dimensioni senza riduzione delle prestazioni
+ Risorse CPU ottimali per l'elaborazione simultanea delle esportazioni
+ Migliore efficienza in termini di costi per i carichi di lavoro di esportazione
## autorizzazioni IAM
La funzionalità di esportazione prevede due ruoli IAM separati:
+ **Ruolo IAM del chiamante**: il principale IAM (utente o ruolo) che invia le richieste all'endpoint dell'API di esportazione. Questo ruolo richiede le autorizzazioni di accesso ai dati di Neptune.
+ **Ruolo IAM di accesso a S3**: il ruolo che Neptune assume per scrivere i dati esportati su Amazon S3. L'ARN di questo ruolo viene passato nel `iamRoleArn` parametro della richiesta di esportazione e deve essere associato al cluster Neptune.
### Autorizzazioni del chiamante (azioni di accesso ai dati di Neptune)
Il principale IAM che chiama l'API di esportazione deve includere le seguenti azioni di accesso ai dati di Neptune nella sua policy IAM:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowNeptuneExportActions",
"Effect": "Allow",
"Action": [
"neptune-db:StartExportJob",
"neptune-db:GetExportJobStatus",
"neptune-db:ListExportJobs",
"neptune-db:CancelExportJob"
],
"Resource": "arn:aws:neptune-db:us-east-1:123456789012:{{cluster-resource-id}}/*"
}
]
}
```
Per ulteriori informazioni, consulta [ Using IAM data-access policy statement. ](iam-dp-actions.md)
### Autorizzazioni per i ruoli di accesso S3
Il ruolo IAM passato nel parametro `iamRoleArn` request deve essere associato al cluster Neptune e deve concedere a Neptune l'autorizzazione di scrittura nel bucket S3 di destinazione. Per istruzioni su come creare un ruolo IAM e associarlo al cluster, consulta [ Creare un ruolo IAM per consentire a Neptune di accedere ad Amazon S3. ](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-CreateRole.html)
**Nota**
L'API di esportazione richiede * autorizzazioni di * scrittura su S3, a differenza del bulk loader che richiede solo l'accesso in lettura. Utilizza la seguente politica di autorizzazione anziché la politica `AmazonS3ReadOnlyAccess` gestita descritta in quella pagina.
Allega la seguente politica di autorizzazioni al ruolo di accesso S3:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowS3WriteForNeptuneExport",
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject",
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:GetBucketPublicAccessBlock"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket",
"arn:aws:s3:::amzn-s3-demo-bucket/*"
]
}
]
}
```
### Autorizzazioni KMS opzionali
Se specifichi a `kmsKeyIdentifier` nella richiesta di esportazione, aggiungi le seguenti autorizzazioni al ruolo di accesso S3:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowKMSForNeptuneExport",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:Encrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:123456789012:key/{{key-id}}"
}
]
}
```
## Endpoint di esportazione
Per esportare i dati, invii richieste HTTP all'`https://your-neptune-endpoint:port/export`endpoint.
## Sintassi della richiesta di esportazione
```
POST https://your-neptune-endpoint:port/export
```
### Intestazioni della richiesta
+ `Content-Type: application/json`
### Corpo della richiesta
```
{
"destination": "string",
"format": "string",
"iamRoleArn": "string",
"region": "string",
"compression": "string",
"kmsKeyIdentifier": "string",
"exportFilter": {
"namedGraphUris": ["string"]
}
}
```
### Parametri della richiesta
**destinazione ** (stringa)
Obbligatorio. L'URI S3 in cui verranno archiviati i dati esportati. Il valore deve essere nel formato `s3://bucket-name/optional-prefix/`.
**formato ** (stringa)
Obbligatorio. Il formato per i dati esportati. Valori validi:
+ `ntriples`— Esportazione dei dati in N-Triples formato
+ `nquads`— Esportazione dei dati in N-Quads formato
**iam RoleArn ** (stringa)
Obbligatorio. L'Amazon Resource Name (ARN) del ruolo IAM che Neptune assume per accedere al bucket S3.
****regione (stringa)
Obbligatorio. Il Regione AWS valore del bucket S3. Deve essere la stessa regione del cluster Neptune.
**compressione ** (stringa)
Opzionale. Formato di compressione per i file esportati. Valori validi:
+ `gz`- Comprimi i file in formato .gz
**KeyIdentifier**kms (stringa)
Opzionale. L'ARN della AWS KMS chiave da usare per crittografare i dati esportati.
**ExportFilter ** (oggetto)
Opzionale. Filtri per esportare selettivamente un sottoinsieme di dati RDF. Disponibile nella versione del motore 1.4.8.0 e successive.
**denominato GraphUris ** (matrice di stringhe)
URI grafici denominati da esportare (massimo 100). Vengono esportati solo i dati contenuti nei grafici specificati. Se un grafico specificato è vuoto, l'esportazione ha esito positivo con un risultato vuoto. Gli URI non validi hanno esito negativo con. `InvalidParameterException`
### Sintassi della risposta
```
{
"status": "string",
"payload": {
"exportId": "string"
}
}
```
**status ** (stringa)
Lo stato HTTP della richiesta.
**exportID ** (stringa)
Un identificatore univoco per l'attività di esportazione.
## Endpoint sullo stato dell'esportazione
Per verificare lo stato di un'attività di esportazione, invii una richiesta HTTP GET all'endpoint di esportazione con l'ID di esportazione.
```
GET https://your-neptune-endpoint:port/export?exportId=export-id
```
### Parametri della richiesta
**ExportID ** (stringa)
Obbligatorio. L'identificatore univoco dell'attività di esportazione.
### Sintassi della risposta
```
{
"status": "string",
"payload": {
"exportId": "string",
"destination": "string",
"status": "string",
"statusReason": "string",
"format": "string",
"iamRoleArn": "string",
"kmsKeyIdentifier": "string",
"exportFilter": {
"namedGraphUris": ["string"]
},
"exportTaskDetails": {
"timeElapsedSeconds": number,
"startTime": number,
"numRecordsWritten": number,
"progressPercentage": number
}
}
}
```
**ExportID ** (stringa)
L'identificatore univoco dell'attività di esportazione.
**destinazione ** (stringa)
L'URI S3 in cui vengono esportati i dati.
**stato ** (stringa)
Lo stato corrente dell'attività di esportazione. Valori validi:
+ `EXPORT_NOT_STARTED`— L'esportazione è stata messa in coda ma non è stata avviata
+ `EXPORT_IN_PROGRESS`— L'esportazione è attualmente in corso
+ `EXPORT_COMPLETED`— Esportazione completata con successo
+ `EXPORT_CANCELLING`— L'esportazione è stata annullata
+ `EXPORT_CANCELLED_BY_USER`— L'esportazione è stata annullata dall'utente
+ `EXPORT_S3_ERROR`— Esportazione non riuscita a causa di un errore di accesso a S3
+ `EXPORT_FAILED`— Esportazione non riuscita a causa di un altro errore
**StatusReason ** (stringa)
Informazioni aggiuntive sullo stato dell'esportazione.
**formato ** (stringa)
Il formato dei dati esportati.
**iam RoleArn ** (stringa)
L'ARN del ruolo IAM utilizzato per l'accesso a S3.
**kms (stringa) KeyIdentifier **
L'ARN della chiave KMS utilizzata per la crittografia, se specificato.
**ExportFilter ** (oggetto)
Il filtro di esportazione applicato, se ne è stato specificato uno nella richiesta.
+ **named GraphUris ** (matrice di stringhe) — Gli URI del grafico denominati utilizzati per filtrare l'esportazione.
**export TaskDetails ** (oggetto)
Dettagli sullo stato di avanzamento dell'attività di esportazione:
+ **time ElapsedSeconds ** (number) — Tempo trascorso dall'inizio dell'esportazione
+ **startTime ** (numero) — Epoca in cui è iniziata l'esportazione
+ **num RecordsWritten ** (number) — Numero di record scritti su S3
+ **progressPercentage ** (numero) — Percentuale di esportazione completata
## Elenca l'endpoint delle esportazioni
Per elencare tutte le attività di esportazione, invii una richiesta HTTP GET all'endpoint di esportazione.
```
GET https://your-neptune-endpoint:port/export
```
### Sintassi della risposta
```
{
"status": "string",
"payload": [
"string"
]
}
```
**payload ** (array)
Una serie di ID di esportazione per tutte le attività di esportazione.
## Annulla l'endpoint di esportazione
Per annullare un'attività di esportazione, invii una richiesta HTTP DELETE all'endpoint di esportazione con l'ID di esportazione.
```
DELETE https://your-neptune-endpoint:port/export?exportId=export-id
```
### Parametri della richiesta
**ExportID ** (stringa)
Obbligatorio. L'identificatore univoco dell'attività di esportazione da annullare.
### Sintassi della risposta
```
{
"status": "string",
"payload": {
"message": "string"
}
}
```
## Formato di output per l'esportazione
### Struttura delle directory S3
I dati esportati sono organizzati nel bucket S3 come segue:
```
s3://your-bucket/export-id/
├── data/
│ ├── part-00000.nt
│ ├── part-00001.nt
│ └── ...
└── export_status.json
```
****dati/ directory
Contiene i file di dati del grafico esportati nel formato specificato.
**file export\_status.json **
Contiene metadati sull'operazione di esportazione.
## Risposte agli errori
### Codici di errore comuni
**BadRequestException**
La richiesta contiene parametri non validi o è già in corso un'esportazione.
**AccessDeniedException**
Il ruolo IAM non dispone delle autorizzazioni necessarie per l'accesso a S3 o KMS.
### Esempio di risposta all'errore
```
{
"code": "BadRequestException",
"requestId": "request-id",
"message": "Export already in progress with ID 'existing-id'. Please wait or cancel it first.",
"detailedMessage": "Detailed error description"
}
```
## Esempi
### Avvia un'esportazione
```
curl -X POST https://your-cluster-endpoint:8182/export \
-H "Content-Type: application/json" \
-d '{
"destination": "s3://my-bucket/exports/",
"format": "ntriples",
"iamRoleArn": "arn:aws:iam::123456789012:role/neptune-export-role",
"region": "us-west-2"
}'
```
### Avvia un'esportazione filtrata (denominata grafici)
```
curl -X POST https://your-cluster-endpoint:8182/export \
-H "Content-Type: application/json" \
-d '{
"destination": "s3://my-bucket/exports/",
"format": "nquads",
"iamRoleArn": "arn:aws:iam::123456789012:role/neptune-export-role",
"region": "us-west-2",
"exportFilter": {
"namedGraphUris": [
"http://example.com/graph1",
"http://example.com/graph2"
]
}
}'
```
### Controlla lo stato dell'esportazione
```
curl -X GET "https://your-cluster-endpoint:8182/export?exportId="
```
### Annulla un'esportazione
```
curl -X DELETE "https://your-cluster-endpoint:8182/export?exportId="
```
## Limitazioni
L'esportazione nativa presenta le seguenti limitazioni:
+ **Supporto per le istanze**: l'esportazione nativa non è supportata sulle istanze Neptune Serverless o sulle repliche di lettura. L'esportazione viene sempre eseguita sull'istanza di scrittura di un cluster di cui è stato eseguito il provisioning.
+ **Un'esportazione per cluster**: su un cluster può essere attiva una sola esportazione alla volta. Se invii una nuova richiesta di esportazione mentre è in corso un'altra esportazione, la richiesta ha esito negativo.
+ **Nessun ripristino automatico**: se il motore si riavvia durante un'esportazione, l'esportazione non riesce e deve essere riavviata dall'inizio. L'avanzamento dell'esportazione non viene mantenuto dopo il riavvio del motore.
+ **Disponibilità dello stato dopo gli eventi del motore**: se il motore si blocca, non è possibile recuperare lo stato dell'esportazione tramite l'API di stato.
+ **Coerenza durante le scritture**: se il cluster serve il traffico di scrittura durante un'esportazione, i dati esportati potrebbero riflettere una visualizzazione parziale o incoerente del grafico. Per garantire un'esportazione coerente, esegui l'esportazione su un cluster clonato.