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.
# Export natif pour les données RDF
L'API d'exportation Neptune vous permet d'exporter des données depuis votre base de données Neptune vers Amazon S3. Vous pouvez exporter les données RDF au N-Quads format N-Triples ou au format.
## Comment fonctionne l'exportation native
L'exportation native s'exécute sur l'instance Writer de votre cluster Neptune et écrit les données exportées vers Amazon S3 à l'aide de téléchargements partitionnés. Étant donné que l'exportation utilise les ressources de calcul de l'instance d'écriture, nous vous recommandons vivement d'exécuter les exportations sur un cluster cloné afin d'éviter tout impact sur les charges de travail de production. Consultez les [ recommandations ](#neptune-native-export-recommendations) pour plus d'informations.
### Débit d'exportation
Le débit d'exportation évolue de manière approximativement linéaire avec une taille d'instance allant jusqu'à`r7i.16xlarge`. À titre d'estimation prudente, attendez-vous à environ ** 50 000 instructions par seconde et par processeur virtuel**.
Utilisez cette formule pour estimer la durée de l'exportation :
```
export_seconds = total_statements / (vCPUs × 50,000)
```
Le débit réel dépend des caractéristiques de l'ensemble de données, notamment de la cardinalité des prédicats, de la complexité des instructions et de la taille du cluster.
## Conditions préalables
Avant d'utiliser l'API d'exportation, vous devez :
+ Disposer d'un cluster de base de données Neptune exécutant la version 1.4.6.0 ou ultérieure (version 1.4.8.0 ou ultérieure pour le support) `exportFilter`
+ [Créez un rôle IAM avec des autorisations pour accéder à votre compartiment S3 ](#neptune-native-export-iam-s3)
+ [Associez le rôle IAM à votre cluster Neptune ](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-add-role-cluster.html)
+ [Configurer un point de terminaison VPC S3 dans le VPC de votre cluster Neptune ](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-vpc.html)
## Recommandations
[Nous vous recommandons vivement d'exécuter l'opération d'exportation sur un cluster cloné sans aucune read/write charge de travail pour éviter tout impact sur les performances de production. ](https://docs.aws.amazon.com/neptune/latest/userguide/manage-console-cloning.html)
Pour un rapport prix/performances optimal, nous vous recommandons d'utiliser des instances ** 16xlarge ** pour les opérations d'exportation. Ce type d'instance fournit :
+ Mémoire suffisante pour gérer de grands ensembles de données sans dégradation des performances
+ Ressources CPU optimales pour le traitement simultané des exportations
+ Meilleur rapport coût-efficacité pour les charges de travail d'exportation
## Autorisations IAM
La fonctionnalité d'exportation implique deux rôles IAM distincts :
+ **Rôle IAM de l'appelant ** : principal IAM (utilisateur ou rôle) qui envoie les demandes au point de terminaison de l'API d'exportation. Ce rôle nécessite les autorisations d'accès aux données de Neptune.
+ **Rôle IAM d'accès S3 ** : rôle assumé par Neptune pour écrire les données exportées vers Amazon S3. Vous transmettez l'ARN de ce rôle dans le `iamRoleArn` paramètre de la demande d'export, et il doit être associé à votre cluster Neptune.
### Autorisations de l'appelant (actions d'accès aux données Neptune)
Le principal IAM qui appelle l'API d'exportation doit disposer des actions d'accès aux données Neptune suivantes dans sa politique 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}}/*"
}
]
}
```
Pour plus d'informations, consultez la section [ Utilisation des déclarations de politique d'accès aux données IAM. ](iam-dp-actions.md)
### Autorisations de rôle d'accès S3
Le rôle IAM transmis dans le paramètre de `iamRoleArn` requête doit être associé à votre cluster Neptune et doit accorder à Neptune l'autorisation d'écrire dans le compartiment S3 cible. Pour savoir comment créer un rôle IAM et l'associer à votre cluster, consultez [ Créer un rôle IAM pour permettre à Neptune d'accéder à Amazon S3. ](https://docs.aws.amazon.com/neptune/latest/userguide/bulk-load-tutorial-IAM-CreateRole.html)
**Note**
L'API d'exportation nécessite * des autorisations d'*écriture sur S3, contrairement au chargeur groupé qui ne nécessite qu'un accès en lecture. Utilisez la politique d'autorisations suivante au lieu de la politique `AmazonS3ReadOnlyAccess` gérée décrite sur cette page.
Associez la politique d'autorisations suivante au rôle d'accès 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/*"
]
}
]
}
```
### Autorisations KMS facultatives
Si vous spécifiez un `kmsKeyIdentifier` dans la demande d'exportation, ajoutez les autorisations suivantes au rôle d'accès 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 d'exportation
Pour exporter des données, vous envoyez des requêtes HTTP au `https://your-neptune-endpoint:port/export` terminal.
## Syntaxe des demandes d'exportation
```
POST https://your-neptune-endpoint:port/export
```
### En-têtes de demandes
+ `Content-Type: application/json`
### Corps de la requête
```
{
"destination": "string",
"format": "string",
"iamRoleArn": "string",
"region": "string",
"compression": "string",
"kmsKeyIdentifier": "string",
"exportFilter": {
"namedGraphUris": ["string"]
}
}
```
### Paramètres de demande
**destination ** (chaîne de caractères)
Obligatoire. L'URI S3 dans lequel les données exportées seront stockées. Doit être au format `s3://bucket-name/optional-prefix/`.
**format ** (chaîne de caractères)
Obligatoire. Format des données exportées. Valeurs valides :
+ `ntriples`— Exporter les données au N-Triples format
+ `nquads`— Exporter les données au N-Quads format
**iam RoleArn ** (chaîne)
Obligatoire. Le nom de ressource Amazon (ARN) du rôle IAM que Neptune assume pour accéder au compartiment S3.
**région ** (chaîne)
Obligatoire. Celui Région AWS du compartiment S3. Il doit s'agir de la même région que votre amas de Neptune.
**compression ** (chaîne)
Facultatif. Format de compression pour les fichiers exportés. Valeurs valides :
+ `gz`- Compressez les fichiers au format .gz
**kms KeyIdentifier ** (chaîne de caractères)
Facultatif. L'ARN de la AWS KMS clé à utiliser pour chiffrer les données exportées.
**ExportFilter ** (objet)
Facultatif. Filtres permettant d'exporter de manière sélective un sous-ensemble de données RDF. Disponible dans les versions du moteur 1.4.8.0 et ultérieures.
**nommé GraphUris ** (tableau de chaînes)
URI de graphes nommés à exporter (maximum 100). Seules les données des graphiques spécifiés sont exportées. Si un graphique spécifié est vide, l'exportation aboutit avec un résultat vide. Les URI non valides échouent avec`InvalidParameterException`.
### Syntaxe de réponse
```
{
"status": "string",
"payload": {
"exportId": "string"
}
}
```
**statut ** (chaîne de caractères)
Le statut HTTP de la requête.
**ExportId (chaîne) **
Identifiant unique pour la tâche d'exportation.
## Point final de statut d'exportation
Pour vérifier l'état d'une tâche d'exportation, vous envoyez une requête HTTP GET au point de terminaison d'exportation avec l'ID d'exportation.
```
GET https://your-neptune-endpoint:port/export?exportId=export-id
```
### Paramètres de demande
**ExportId (chaîne) **
Obligatoire. Identifiant unique de la tâche d'exportation.
### Syntaxe de réponse
```
{
"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 (chaîne) **
Identifiant unique de la tâche d'exportation.
**destination ** (chaîne de caractères)
L'URI S3 vers lequel les données sont exportées.
**statut ** (chaîne de caractères)
État actuel de la tâche d'exportation. Valeurs valides :
+ `EXPORT_NOT_STARTED`— L'exportation a été mise en file d'attente mais n'a pas commencé
+ `EXPORT_IN_PROGRESS`— L'exportation est en cours
+ `EXPORT_COMPLETED`— Exportation terminée avec succès
+ `EXPORT_CANCELLING`— L'exportation est en cours d'annulation
+ `EXPORT_CANCELLED_BY_USER`— L'exportation a été annulée par l'utilisateur
+ `EXPORT_S3_ERROR`— L'exportation a échoué en raison d'une erreur d'accès S3
+ `EXPORT_FAILED`— L'exportation a échoué en raison d'une autre erreur
**StatusReason (chaîne de ** caractères)
Informations supplémentaires sur le statut des exportations.
**format ** (chaîne de caractères)
Format des données exportées.
**iam RoleArn ** (chaîne)
L'ARN du rôle IAM utilisé pour l'accès S3.
**kms KeyIdentifier ** (chaîne de caractères)
L'ARN de la clé KMS utilisée pour le chiffrement, s'il est spécifié.
**ExportFilter ** (objet)
Le filtre d'exportation qui a été appliqué, s'il a été spécifié dans la demande.
+ **named GraphUris ** (tableau de chaînes) — Les URI des graphes nommés utilisés pour filtrer l'exportation.
**exportation TaskDetails ** (objet)
Informations détaillées sur la progression de la tâche d'exportation :
+ **time ElapsedSeconds ** (nombre) — Temps écoulé depuis le début de l'exportation
+ **StartTime ** (number) — Heure à laquelle l'exportation a commencé
+ **num RecordsWritten ** (number) — Nombre d'enregistrements écrits sur S3
+ ****ProgressPercentage (nombre) — Pourcentage d'exportation terminée
## Terminer les exportations de la liste
Pour répertorier toutes les tâches d'exportation, vous envoyez une requête HTTP GET au point de terminaison d'exportation.
```
GET https://your-neptune-endpoint:port/export
```
### Syntaxe de réponse
```
{
"status": "string",
"payload": [
"string"
]
}
```
**charge utile ** (matrice)
Tableau d'identifiants d'exportation pour toutes les tâches d'exportation.
## Annuler l'endpoint d'exportation
Pour annuler une tâche d'exportation, vous envoyez une requête HTTP DELETE au point de terminaison d'exportation avec l'ID d'exportation.
```
DELETE https://your-neptune-endpoint:port/export?exportId=export-id
```
### Paramètres de demande
**ExportId (chaîne) **
Obligatoire. Identifiant unique de la tâche d'exportation à annuler.
### Syntaxe de réponse
```
{
"status": "string",
"payload": {
"message": "string"
}
}
```
## Format de sortie d'exportation
### Structure du répertoire S3
Les données exportées sont organisées dans votre compartiment S3 comme suit :
```
s3://your-bucket/export-id/
├── data/
│ ├── part-00000.nt
│ ├── part-00001.nt
│ └── ...
└── export_status.json
```
**données/répertoire **
Contient les fichiers de données graphiques exportés dans le format spécifié.
**fichier export\_status.json **
Contient des métadonnées relatives à l'opération d'exportation.
## Réponses d'erreur
### Codes d'erreur courants
**BadRequestException**
La demande contient des paramètres non valides ou une exportation est déjà en cours.
**AccessDeniedException**
Le rôle IAM ne dispose pas des autorisations requises pour l'accès S3 ou KMS.
### Exemple de réponse d'erreur
```
{
"code": "BadRequestException",
"requestId": "request-id",
"message": "Export already in progress with ID 'existing-id'. Please wait or cancel it first.",
"detailedMessage": "Detailed error description"
}
```
## Exemples
### Lancer une exportation
```
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"
}'
```
### Lancer une exportation filtrée (nommée graphes)
```
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"
]
}
}'
```
### Vérifier l'état de l'exportation
```
curl -X GET "https://your-cluster-endpoint:8182/export?exportId="
```
### Annuler une exportation
```
curl -X DELETE "https://your-cluster-endpoint:8182/export?exportId="
```
## Limitations
L'exportation native présente les limites suivantes :
+ **Prise en charge des instances ** : l'exportation native n'est pas prise en charge sur les instances Neptune Serverless ni sur les répliques en lecture. L'exportation s'exécute toujours sur l'instance d'écriture d'un cluster provisionné.
+ **Une exportation par cluster ** : une seule exportation peut être active sur un cluster à la fois. Si vous soumettez une nouvelle demande d'exportation alors qu'une autre exportation est en cours, la demande échoue.
+ **Pas de reprise automatique ** — Si le moteur redémarre pendant une exportation, l'exportation échoue et doit être redémarrée depuis le début. La progression de l'exportation n'est pas conservée lors des redémarrages du moteur.
+ **Disponibilité du statut après des événements ** liés au moteur : si le moteur tombe en panne, vous ne pouvez pas récupérer l'état de l'exportation via l'API status.
+ **Cohérence lors des écritures ** : si votre cluster gère le trafic d'écriture lors d'une exportation, les données exportées peuvent refléter une vue partielle ou incohérente du graphique. Pour garantir une exportation cohérente, exécutez l'exportation sur un cluster cloné.