Commande Neptune - Amazon Neptune

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.

Commande Neptune

Charge les données d'un compartiment Amazon S3 dans une instance de base de données Neptune.

Pour charger des données, vous devez envoyer une demande POST HTTP au point de terminaison https://your-neptune-endpoint:port/loader. Les paramètres de la demande loader peuvent être envoyés dans le corps POST ou en tant que paramètres encodés en URL.

Important

Le type MIME doit être application/json.

Le compartiment S3 doit se situer dans le mêmeAWSRégion en tant que cluster.

Note

Vous pouvez charger des données cryptées depuis Amazon S3 si elles ont été cryptées à l'aide d'Amazon S3SSE-S3Mode. Dans ce cas, Neptune peut se faire passer pour vos informations d'identification et émettres3:getObjectappelle en votre nom.

Vous pouvez également charger des données cryptées depuis Amazon S3 qui ont été cryptées à l'aide duSSE-KMSmode, à condition que votre rôle IAM inclut les autorisations nécessaires pour accéderAWS KMS. Sans les autorisations AWS KMS appropriées, l'opération de chargement en bloc échoue et renvoie une réponse LOAD_FAILED.

Neptune ne prend actuellement pas en charge le chargement de données Amazon S3 cryptées à l'aide duSSE-CMode.

Vous n'avez pas à attendre qu'une tâche de chargement soit terminée avant d'en commencer une autre. Neptune peut mettre en file d'attente jusqu'à 64 demandes de travail à la fois, à condition quequeueRequestles paramètres sont tous définis sur"TRUE". Si vous ne souhaitez pas qu'une tâche de chargement soit mise en file d'attente, vous pouvez configurer sonqueueRequestparamètre to"FALSE"(valeur par défaut), de sorte que la tâche de chargement échoue si une autre est déjà en cours.

Vous pouvez utiliser le paramètre dependencies pour mettre en file d'attente une tâche qui doit être exécutée uniquement une fois que les tâches précédentes spécifiées dans la file d'attente se sont achevées correctement. Si vous faites cela et que l'une des tâches spécifiées échoue, votre tâche ne sera pas exécutée et son statut sera défini sur LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

Syntaxe de la requête Neptune Loader

{ "source" : "string", "format" : "string", "iamRoleArn" : "string", "mode": "NEW|RESUME|AUTO", "region" : "us-east-1", "failOnError" : "string", "parallelism" : "string", "parserConfiguration" : { "baseUri" : "http://base-uri-string", "namedGraphUri" : "http://named-graph-string" }, "updateSingleCardinalityProperties" : "string", "queueRequest" : "TRUE", "dependencies" : [\"load_A_id\", \"load_B_id\"] }

Paramètres de demande Neptune Loader

  • source— Un URI Amazon S3.

    Dans laSOURCELe paramètre accepte un URI Amazon S3 qui identifie un fichier unique, plusieurs fichiers, un dossier ou plusieurs dossiers. Neptune charge chaque fichier de données dans n'importe quel dossier spécifié.

    L'URI peut être à l'un des formats suivants.

    • s3://bucket_name/object-key-name

    • https://s3.amazonaws.com/bucket_name/object-key-name

    • https://s3.us-east-1.amazonaws.com/bucket_name/object-key-name

    Dans laobject-key-nameélément de l'URI est équivalent àpréfixeparamètre dans un Amazon S3ListObjectsAppel d'API. Il identifie tous les objets du compartiment Amazon S3 spécifié dont le nom commence par ce préfixe. Il peut s'agir d'un seul fichier ou dossier, ou de plusieurs fichiers et/ou dossiers.

    Le ou les dossiers spécifiés peuvent contenir plusieurs fichiers de sommets et plusieurs fichiers de bord.

  • format— Le format des données. Pour plus d'informations sur les formats de données pour le NeptuneLoadercommande, voirUtilisation du chargeur en vrac Amazon Neptune pour ingérer des données.

  • iamRoleArn— L'Amazon Resource Name (ARN) du rôle IAM à assumer par l'instance de base de données Neptune pour accéder au compartiment S3. Pour plus d'informations sur la création d'un rôle ayant accès à Amazon S3, puis sur son association à un cluster Neptune, voirPrérequis : Rôle IAM et accès Amazon S3.

  • region— Leregionle paramètre doit correspondre àAWSRégion du cluster et du compartiment S3.

    Amazon Neptune est disponible dans les régions suivantes :

    • USA Est (Virginie -du Nord) :us-east-1

    • USA East (Ohio) :us-east-2

    • USA Ouest (Californie du Nord) :us-west-1

    • USA Ouest (Oregon) :us-west-2

    • Canada (Centre) :ca-central-1

    • Amérique du Sud (São Paulo) :sa-east-1

    • Europe (Stockholm) :eu-north-1

    • Europe (Irlande) :eu-west-1

    • Europe (Londres) :eu-west-2

    • Europe (Paris) :eu-west-3

    • Europe (Francfort) :eu-central-1

    • Moyen-Orient (Bahreïn) :me-south-1

    • Afrique (Le Cap) :af-south-1

    • Asie-Pacifique (Hong Kong) :ap-east-1

    • Asie-Pacifique (Tokyo)ap-northeast-1

    • Asie-Pacifique (Séoul)ap-northeast-2

    • Asie-Pacifique (Singapour) :ap-southeast-1

    • Asie-Pacifique (Sydney) :ap-southeast-2

    • Asie-Pacifique (Mumbai) :ap-south-1

    • Chine (Pékin) :cn-north-1

    • Chine (Ningxia) :cn-northwest-1

    • AWS GovCloud (US-West) :us-gov-west-1

    • AWS GovCloud (US-East) :us-gov-east-1

  • mode— Le mode de charge de la tâche.

    Valeurs autorisées : RESUME, NEW, AUTO

    Valeur par défaut : AUTO

    • RESUME— En mode RESUME, le chargeur recherche une charge précédente provenant de cette source et, s'il en trouve une, reprend cette tâche de chargement. Si aucune tâche de chargement précédente n'est trouvée, le chargeur s'arrête.

      Le chargeur évite de recharger les fichiers qui ont été chargés avec succès lors d'une tâche précédente. Il essaie uniquement de traiter les fichiers ayant échoué. Si vous avez supprimé des données précédemment chargées de votre cluster Neptune, ces données ne sont pas rechargées dans ce mode. Si une tâche de chargement précédente a correctement chargé tous les fichiers de la même source, rien n'est rechargé et le chargeur renvoie le résultat avec succès.

    • NEW— En mode NOUVEAU, crée une nouvelle demande de chargement indépendamment des chargements précédents. Vous pouvez utiliser ce mode pour recharger toutes les données d'une source après avoir supprimé les données précédemment chargées de votre cluster Neptune, ou pour charger de nouvelles données disponibles sur la même source.

    • AUTO— En mode AUTO, le chargeur recherche une tâche de chargement précédente provenant de la même source, et s'il en trouve une, reprend cette tâche, comme dansRESUMEMode.

      Si le chargeur ne trouve pas de tâche de chargement précédente à partir de la même source, il charge toutes les données de la source, exactement comme en mode NEW.

  • failOnError— Un indicateur permettant de désactiver l'arrêt complet d'une erreur.

    Valeurs autorisées : "TRUE", "FALSE".

    Valeur par défaut : "TRUE".

    Lorsque ce paramètre est défini sur "FALSE", le chargeur essaie de charger toutes les données à l'emplacement spécifié, en ignorant les entrées contenant des erreurs.

    Lorsque ce paramètre est défini sur "TRUE", le chargeur s'arrête dès qu'il rencontre une erreur. Les données chargées jusqu'à ce point persistent.

  • parallelism— Il s'agit d'un paramètre facultatif qui peut être défini pour réduire le nombre de threads utilisés par le processus de chargement en bloc.

    Valeurs autorisées :

    • LOW— Le nombre de threads utilisés est le nombre de vCPUs disponibles divisé par 8.

    • MEDIUM— Le nombre de threads utilisés est le nombre de vCPUs disponibles divisé par 2.

    • HIGH— Le nombre de threads utilisés est identique au nombre de vCPUs disponibles.

    • OVERSUBSCRIBE— Le nombre de threads utilisés est le nombre de vCPUs disponibles multiplié par 2. Si cette valeur est utilisée, le chargeur en bloc accepte toutes les ressources disponibles.

      Cela ne signifie pas, toutefois, queOVERSUBSCRIBEle réglage entraîne une utilisation du processeur à 100 %. Comme l'opération de chargement est limitée aux E/S, le taux d'utilisation du processeur le plus élevé auquel on peut s'attendre se situe entre 60 % et 70 %.

    Valeur par défaut : HIGH

    Dans laparallelismle réglage peut parfois entraîner un blocage entre les threads lors du chargement de données OpenCypher. Lorsque cela se produit, Neptune renvoie leLOAD_DATA_DEADLOCKErreur. Vous pouvez généralement résoudre le problème en définissantparallelismà une valeur inférieure et réessayez la commande de chargement.

  • parserConfiguration— Un objet facultatif avec des valeurs de configuration supplémentaires pour l'analyseur. Chacun des paramètres enfants est également facultatif :

    Nom Exemple de valeur Description
    namedGraphUri http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph The default graph for all RDF formats when no graph is specified (for non-quads formats and NQUAD entries with no graph). The default is http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph
    URI de base http://aws.amazon.com/neptune/default The base URI for RDF/XML and Turtle formats. The default is http://aws.amazon.com/neptune/default.
    allowEmptyStrings true

    Les utilisateurs de Gremlin doivent pouvoir transmettre des valeurs de chaîne vides (« ») en tant que propriétés de nœud et de bord lors du chargement de données CSV. SiallowEmptyStringsest défini surfalse(valeur par défaut), ces chaînes vides sont traitées comme des valeurs nulles et ne sont pas chargées.

    SiallowEmptyStringsest défini surtrue, le chargeur traite les chaînes vides comme des valeurs de propriété valides et les charge en conséquence.

    Pour plus d'informations, consultez Graphe par défaut SPARQL et graphes nommés.

  • updateSingleCardinalityProperties— Il s'agit d'un paramètre facultatif qui contrôle la manière dont le chargeur en vrac traite une nouvelle valeur pour les propriétés de sommet ou d'arête à cardinalité unique. Ceci n'est pas pris en charge pour le chargement de données OpenCypher (voirChargement de données OpenCypher).

    Valeurs autorisées : "TRUE", "FALSE".

    Valeur par défaut : "FALSE".

    Par défaut, ou lorsque updateSingleCardinalityProperties est explicitement défini sur "FALSE", le chargeur traite une nouvelle valeur comme une erreur, car elle ne respecte pas la cardinalité unique.

    En revanche, lorsque updateSingleCardinalityProperties est défini sur "TRUE", le chargeur en bloc remplace la valeur existante par la nouvelle. Si plusieurs valeurs de propriété de sommet à cardinalité unique ou d'arête sont fournies dans le ou les fichiers source en cours de chargement, la valeur finale à l'issue du chargement en bloc peut être une de ces nouvelles valeurs. Le chargeur garantit uniquement que la valeur existante a été remplacée par une des nouvelles.

  • queueRequest— Il s'agit d'un paramètre d'indicateur facultatif qui indique si la demande de chargement peut être mise en file d'attente ou non.

    Vous n'avez pas à attendre qu'une tâche de chargement soit terminée avant de lancer la suivante, car Neptune peut mettre en file d'attente jusqu'à 64 tâches à la fois, à condition que leurqueueRequestles paramètres sont tous définis sur"TRUE".

    Si le paramètre queueRequest est omis ou défini sur "FALSE", la demande de chargement échouera si une autre tâche de chargement est déjà en cours d'exécution.

    Valeurs autorisées : "TRUE", "FALSE".

    Valeur par défaut : "FALSE".

  • dependencies— Il s'agit d'un paramètre facultatif qui peut subordonner une demande de chargement en file d'attente à la réussite d'une ou de plusieurs tâches précédentes de la file d'attente.

    Neptune peut mettre en file d'attente jusqu'à 64 demandes de chargement à la fois, si leurqueueRequestles paramètres sont définis sur"TRUE". Le paramètre dependencies vous permet de rendre l'exécution d'une telle requête en file d'attente dépendante de la réussite d'une ou de plusieurs requêtes précédentes spécifiées dans la file d'attente.

    Par exemple, si les charges Job-A et Job-B sont indépendantes l'une de l'autre, mais que la charge Job-C a besoin que Job-A et Job-B soient terminées avant de commencer, procédez comme suit :

    1. Soumettez load-job-A et load-job-B l'une après l'autre dans n'importe quel ordre, et enregistrez leurs ID de chargement.

    2. Soumettez load-job-C avec les ID de chargement des deux tâches dans son domaine dependencies :

    "dependencies" : [\"job_A_load_id\", \"job_B_load_id\"]

    En raison du paramètre dependencies, le chargeur en bloc ne démarrera pas Job-C avant que Job-A et Job-B soient terminées avec succès. Si l'une des d'eux échoue, Job-C ne sera pas exécuté et son statut sera défini sur LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

    Vous pouvez configurer plusieurs niveaux de dépendance de cette façon, de sorte que l'échec d'une tâche entraîne l'annulation de toutes les demandes qui en dépendent directement ou indirectement.

  • userProvidedEdgeIds— Ce paramètre est requis uniquement lors du chargement de données OpenCypher contenant des ID de relation. Elle doit être incluse et réglée surTruelorsque les ID de relation OpenCypher sont explicitement fournis dans les données de chargement (recommandé).

    LorsqueuserProvidedEdgeIdsest absent ou réglé surTrue, un:IDUne colonne doit être présente dans chaque fichier de relations du chargement.

    LorsqueuserProvidedEdgeIdsest présent et réglé surFalse, fichiers de relations dans le chargementne doit pasContenir un:IDColonne. Au lieu de cela, le chargeur Neptune génère automatiquement un identifiant pour chaque relation.

    Il est utile de fournir des identifiants de relation de manière explicite afin que le chargeur puisse reprendre le chargement après correction d'une erreur dans les données CSV, sans avoir à recharger les relations déjà chargées. Si aucun identifiant de relation n'a été attribué explicitement, le chargeur ne peut pas reprendre un chargement ayant échoué si un fichier de relations a dû être corrigé, et doit à la place recharger toutes les relations.

  • accessKey[obsolète]ID de clé d'accès d'un rôle IAM ayant accès au compartiment S3 et aux fichiers de données.

    Le paramètre iamRoleArn est recommandé à la place. Pour plus d'informations sur la création d'un rôle ayant accès à Amazon S3, puis sur son association à un cluster Neptune, voirPrérequis : Rôle IAM et accès Amazon S3.

    Pour plus d'informations, consultez Clés d'accès (ID de clé d'accès et clé d'accès secrète).

  • secretKey[obsolète]Dans laiamRoleArnLe paramètre est recommandé à la place. Pour plus d'informations sur la création d'un rôle ayant accès à Amazon S3, puis sur son association à un cluster Neptune, voirPrérequis : Rôle IAM et accès Amazon S3.

    Pour plus d'informations, consultez Clés d'accès (ID de clé d'accès et clé d'accès secrète).

Considérations spéciales concernant le chargement de données OpenCypher

  • Lorsque vous chargez des données OpenCypher au format CSV, le paramètre de format doit être défini suropencypher.

  • Dans laupdateSingleCardinalityPropertiesLe paramètre n'est pas pris en charge pour les chargements OpenCypher car toutes les propriétés d'OpenCypher ont une cardinalité unique. Le format de chargement OpenCrypher ne prend pas en charge les tableaux, et si une valeur d'identifiant apparaît plusieurs fois, elle est traitée comme un doublon ou comme une erreur d'insertion (voir ci-dessous).

  • Le chargeur Neptune gère les doublons qu'il rencontre dans les données OpenCypher de la manière suivante :

    • Si le chargeur rencontre plusieurs lignes avec le même identifiant de nœud, elles sont fusionnées selon la règle suivante :

      • Toutes les étiquettes des lignes sont ajoutées au nœud.

      • Pour chaque propriété, une seule des valeurs de propriété est chargée. Le choix de celui à charger n'est pas déterministe.

    • Si le chargeur rencontre plusieurs lignes avec le même identifiant de relation, une seule d'entre elles est chargée. Le choix de celui à charger n'est pas déterministe.

    • Le chargeur ne met jamais à jour les valeurs de propriété d'un nœud ou d'une relation existant dans la base de données s'il rencontre des données de chargement portant l'ID du nœud ou de la relation existants. Toutefois, il charge les étiquettes et les propriétés des nœuds qui ne sont pas présentes dans le nœud ou la relation existants.

  • Bien que vous n'ayez pas à attribuer d'ID aux relations, c'est généralement une bonne idée (voir leuserProvidedEdgeIdsparamètre ci-dessus). Sans ID de relation explicites, le chargeur doit recharger toutes les relations en cas d'erreur dans un fichier de relations, plutôt que de reprendre le chargement là où il a échoué.

    De plus, si les données de chargement ne contiennent pas d'ID de relation explicites, le chargeur n'a aucun moyen de détecter les relations dupliquées.

Voici un exemple de commande de chargement OpenCypher :

curl -X POST https://your-neptune-endpoint:port/loader \ -H 'Content-Type: application/json' \ -d ' { "source" : "s3://bucket-name/object-key-name", "format" : "opencypher", "userProvidedEdgeIds": "TRUE", "iamRoleArn" : "arn:aws:iam::account-id:role/role-name", "region" : "region", "failOnError" : "FALSE", "parallelism" : "MEDIUM", }'

La réponse du chargeur est identique à la normale. Par exemple :

{ "status" : "200 OK", "payload" : { "loadId" : "guid_as_string" } }

Syntaxe de la réponse Neptune Loader

{ "status" : "200 OK", "payload" : { "loadId" : "guid_as_string" } }

200 OK

Une tâche de chargement démarrée avec succès renvoie un code 200.

Erreurs Neptune Loader

Lorsqu'une erreur se produit, un objet JSON est renvoyé dans le BODY (corps) de la réponse. L'objet message contient une description de l'erreur.

Catégories d'erreurs

  • Error 400— Les erreurs de syntaxe renvoient un HTTP400erreur de requête incorrecte. Le message décrit l'erreur.

  • Error 500— Une requête valide qui ne peut pas être traitée renvoie un HTTP500erreur interne du serveur. Le message décrit l'erreur.

Voici les messages d'erreur possibles du chargeur avec une description de l'erreur.

Messages d'erreur du chargeur

  • Couldn't find the AWS credential for iam_role_arn  (HTTP 400)

    Les informations d'identification n'ont pas été trouvées. Vérifiez les informations d'identification fournies par rapport à la console IAM ouAWS CLISortie.

  • S3 bucket not found for source  (HTTP 400)

    Le compartiment S3 n'existe pas. Vérifiez le nom du compartiment.

  • The source source-uri does not exist/not reachable  (HTTP 400)

    Aucun fichier correspondant n'a été trouvé dans le compartiment S3.

  • Unable to connect to S3 endpoint. Provided source = source-uri and region = aws-region  (HTTP 500)

    Impossible de vous connecter à Amazon S3. La région doit correspondre à la région du cluster. Assurez-vous de disposer d'un point de terminaison de VPC. Pour plus d'informations sur la création d'un point de terminaison VPC, consultez Création d'un point Amazon S3 terminaison d'un VPC.

  • Bucket is not in provided Region (aws-region)  (HTTP 400)

    Le compartiment doit être dans le mêmeAWSRégion en tant qu'instance de base de données Neptune.

  • Unable to perform S3 list operation  (HTTP 400)

    L'utilisateur ou le rôle IAM fourni ne dispose pas d'autorisations List sur le compartiment ou le dossier. Vérifiez la stratégie ou la liste de contrôle d'accès (ACL) sur le compartiment.

  • Start new load operation not permitted on a read replica instance  (HTTP 405)

    Le chargement est une opération d'écriture. Réessayez le chargement sur le point de terminaison de cluster en lecture/écriture.

  • Failed to start load because of unknown error from S3  (HTTP 500)

    Amazon S3 a renvoyé une erreur inconnue. Contactez AWS Support.

  • Invalid S3 access key  (HTTP 400)

    La clé d'accès n'est pas valide. Vérifiez les informations d'identification fournies.

  • Invalid S3 secret key  (HTTP 400)

    La clé secrète n'est pas valide. Vérifiez les informations d'identification fournies.

  • Max concurrent load limit breached  (HTTP 400)

    Si une demande de chargement est soumise sans "queueRequest" : "TRUE", et qu'une tâche de chargement est en cours d'exécution, la demande échouera avec cette erreur.

  • Failed to start new load for the source "source name". Max load task queue size limit breached. Limit is 64  (HTTP 400)

    Neptune permet de mettre en file d'attente jusqu'à 64 tâches de chargement à la fois. Si une demande de chargement supplémentaire est soumise à la file d'attente alors qu'elle contient déjà 64 tâches, la demande échoue avec ce message.

Exemples de Neptune

Exemple Requête

Voici une demande envoyée via HTTP POST à l'aide de la commande curl. Il charge un fichier au format Neptune CSV. Pour plus d'informations, consultez Format de données de chargement Gremlin.

curl -X POST \ -H 'Content-Type: application/json' \ https://your-neptune-endpoint:port/loader -d ' { "source" : "s3://bucket-name/object-key-name", "format" : "csv", "iamRoleArn" : "ARN for the IAM role you are using", "region" : "region", "failOnError" : "FALSE", "parallelism" : "MEDIUM", "updateSingleCardinalityProperties" : "FALSE", "queueRequest" : "FALSE" }'

Exemple Réponse

{ "status" : "200 OK", "payload" : { "loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5" } }