Sintaxis de la solicitud Parámetros de la solicitud Sintaxis de la respuesta Errores Ejemplos

Comando del programa de carga de Neptune

Carga datos desde un bucket de Amazon S3 en una instancia de base de datos de Neptune.

Para cargar los datos, debe enviar una solicitud HTTP POST al punto de enlace https://your-neptune-endpoint:port/loader. Los parámetros de la solicitud loader se pueden enviar en el cuerpo de POST o como parámetros codificados en URL.

importante

El tipo MIME debe ser application/json.

El depósito S3 debe estar en la misma AWS región que el clúster.

nota

Puede cargar datos cifrados desde Amazon S3 si se cifran mediante el modo SSE-S3 de Amazon S3. En ese caso, Neptune es capaz de suplantar sus credenciales y emitir llamadas de s3:getObject en su nombre.

También puede cargar datos cifrados desde Amazon S3 que se hayan cifrado mediante el modo SSE-KMS, siempre que el rol de IAM incluya los permisos necesarios para obtener acceso a AWS KMS. Sin AWS KMS los permisos adecuados, la operación de carga masiva falla y devuelve una LOAD_FAILED respuesta.

Actualmente Neptune no admite la carga de datos cifrados de Amazon S3 con el modo SSE-C.

No tiene que esperar a que finalice un trabajo de carga para iniciar otro. Neptune puede poner en cola hasta 64 solicitudes de trabajo a la vez, siempre que todos sus parámetros queueRequest estén configurados como "TRUE". El orden de espera de los trabajos será first-in-first-out (FIFO). Por otro lado, si no desea que un trabajo de carga esté en cola, puede establecer su parámetro queueRequest en "FALSE" (valor predeterminado), de modo que se producirá un error en el trabajo de carga si otro ya está en curso.

Puede utilizar el parámetro dependencies para poner en cola un trabajo que solo debe ejecutarse después de que los trabajos anteriores especificados en la cola se hayan completado correctamente. Si lo hace y se produce un error en cualquiera de esos trabajos especificados, su trabajo no se ejecutará y el estado se establecerá en LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

Sintaxis de las solicitudes del programa de carga de Neptune


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

Parámetros de solicitudes del programa de carga de Neptune

source: un URI de Amazon S3.

El parámetro SOURCE acepta un URI de Amazon S3 que identifica un solo archivo, varios archivos, una carpeta o varias carpetas. Neptune carga todos los archivos de datos de cualquier carpeta especificada.

El URI puede tener cualquiera de los siguientes formatos:
- 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
El object-key-name elemento del URI equivale al parámetro de prefijo en una llamada a la ListObjectsAPI de Amazon S3. Identifica todos los objetos del bucket de Amazon S3 especificado cuyos nombres comienzan con ese prefijo. Puede ser un único archivo o carpeta o varios archivos o carpetas.

La carpeta o carpetas especificadas pueden contener varios archivos de vértice y varios archivos de borde.

Por ejemplo, si tuviera la siguiente estructura de carpetas y archivos en un bucket de Amazon S3 denominadobucket-name:
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
s3://bucket-name/bcd
```
Si el parámetro de origen se especifica comos3://bucket-name/a, se cargarán los tres primeros archivos.
```
s3://bucket-name/a/bc
s3://bucket-name/ab/c
s3://bucket-name/ade
```
format: el formato de los datos. Para obtener más información acerca de los formatos de los datos para el comando Loader de Neptune, consulte Uso del programa de carga masiva de Amazon Neptune para adquirir datos.
Valores permitidos
- csv para el formato de datos CSV de Gremlin.
- opencypher para el formato de datos CSV de openCypher.
- ntriples para el formato de datos RDF N-Triples.
- nquads para el formato de datos RDF N-Quads.
- rdfxml para el formato de datos RDF RDF\XML.
- turtle para el formato de datos RDF de Turtle.
iamRoleArn: nombre de recurso de Amazon (ARN) para que la instancia de base de datos de Neptune asuma el rol de IAM para obtener acceso al bucket de S3. Para obtener información acerca de cómo crear un rol con acceso a Amazon S3 y, después, asociarlo a un clúster de Neptune, consulte Requisitos previos: rol de IAM y acceso a Amazon S3.

A partir de la versión 1.2.1.0.R3 del motor, también puede encadenar varias funciones de IAM si la instancia de base de datos Neptune y el bucket de Amazon S3 están ubicados en cuentas diferentes. AWS En este caso, iamRoleArn contiene una lista de ARN de roles separados por comas, tal y como se describe en Encadenamiento de roles de IAM en Amazon Neptune. Por ejemplo:
```
curl -X POST https://localhost:8182/loader \
  -H 'Content-Type: application/json' \
  -d '{
        "source" : "s3://(the target bucket name)/(the target date file name)",
        "iamRoleArn" : "arn:aws:iam::(Account A ID):role/(RoleA),arn:aws:iam::(Account B ID):role/(RoleB),arn:aws:iam::(Account C ID):role/(RoleC)",
        "format" : "csv",
        "region" : "us-east-1"
      }'
```
region— El region parámetro debe coincidir con la AWS región del clúster y el bucket de S3.

Amazon Neptune está disponible en las siguientes regiones de :
- Este de EE. UU. (Norte de Virginia): us-east-1
- Este de EE. UU. (Ohio): us-east-2
- Oeste de EE. UU. (Norte de California): us-west-1
- Oeste de EE. UU. (Oregón): us-west-2
- Canadá (centro): ca-central-1
- América del Sur (São Paulo): sa-east-1
- Europa (Estocolmo): eu-north-1
- Europa (Irlanda): eu-west-1
- Europa (Londres): eu-west-2
- Europa (París): eu-west-3
- Europa (Fráncfort): eu-central-1
- Medio Oriente (Baréin): me-south-1
- Medio Oriente (EAU): me-central-1
- Israel (Tel Aviv): il-central-1
- África (Ciudad del Cabo): af-south-1
- Asia Pacífico (Hong Kong): ap-east-1
- Asia-Pacífico (Tokio): ap-northeast-1
- Asia-Pacífico (Seúl): ap-northeast-2
- Asia-Pacífico (Osaka): ap-northeast-3
- Asia-Pacífico (Singapur): ap-southeast-1
- Asia-Pacífico (Sídney): ap-southeast-2
- Asia-Pacífico (Bombay): ap-south-1
- China (Pekín): cn-north-1
- China (Ningxia): cn-northwest-1
- AWS GovCloud (EE. UU.-Oeste): us-gov-west-1
- AWS GovCloud (EE. UU.-Este): us-gov-east-1
mode: el modo de trabajo de carga.

Valores permitidos: RESUME, NEW, AUTO.

Valor predeterminado: AUTO
- RESUME: en el modo RESUME, el programa de carga busca una carga anterior de este origen y, si encuentra una, reanuda ese trabajo de carga. Si no se encuentra ningún trabajo de carga anterior, el programa de carga se detiene.
  
  El programa de carga evita la recarga de archivos cargados correctamente en un trabajo anterior. Solo intenta procesar los archivos con errores. Si ha eliminado los datos cargados anteriormente del clúster de Neptune, esos datos no se vuelven a cargar en este modo. Si un trabajo de carga anterior ha cargado todos los archivos del mismo origen correctamente, no se vuelve a cargar nada y el programa de carga devuelve una operación correcta.
- NEW: en el modo NEW, crea una solicitud de carga, independientemente de cualquier carga anterior. Puede utilizar este modo para volver a cargar todos los datos de un origen después de descartar los datos cargados anteriormente desde el clúster de Neptune o bien para cargar nuevos datos disponibles en el mismo origen.
- AUTO: en el modo AUTO, el programa de carga busca un trabajo de carga anterior del mismo origen y, si encuentra uno, lo reanuda, igual que en el modo RESUME.
  
  Si el programa de carga no encuentra un trabajo de carga anterior del mismo origen, carga todos los datos del origen, al igual que en el modo NEW.
failOnError: un indicador para activar la detención total al encontrar un error.

Valores permitidos: "TRUE" y "FALSE".

Valor predeterminado: "TRUE".

Cuando este parámetro se establece en "FALSE", el programa de carga intenta cargar todos los datos de la ubicación especificada, omitiendo cualquier entrada con errores.

Cuando este parámetro se establece en "TRUE", el programa de carga se detiene en cuanto encuentra un error. Los datos cargados hasta ese momento persisten.
parallelism: es un parámetro opcional que se puede establecer para reducir el número de subprocesos utilizados por el proceso de carga masiva.

Valores permitidos:
- LOW: el número de subprocesos utilizados es el número de vCPU disponibles dividido entre 8.
- MEDIUM: el número de subprocesos utilizados es el número de vCPU disponibles dividido entre 2.
- HIGH: el número de subprocesos utilizados es el mismo número de vCPU disponibles.
- OVERSUBSCRIBE: el número de subprocesos utilizados es el número de vCPU disponibles multiplicado por 2. Si se utiliza este valor, el programa de carga masiva absorbe todos los recursos disponibles.
  
  Sin embargo, esto no significa que el ajuste de OVERSUBSCRIBE dé como resultado un uso del 100 % de la CPU. Dado que la operación de carga está vinculada a la E/S, la máxima utilización de la CPU que cabe esperar se sitúa entre el 60 y el 70 %.
Valor predeterminado: HIGH

En ocasiones, este ajuste de parallelism puede provocar un bloqueo entre los subprocesos al cargar datos de openCypher. Cuando esto ocurre, Neptune devuelve el error LOAD_DATA_DEADLOCK. Por lo general, puede solucionar el problema configurando parallelism en un ajuste inferior y volviendo a intentar ejecutar el comando de carga.

parserConfiguration: objeto opcional con valores de configuración de analizador adicionales. Cada uno de los parámetros secundarios también es opcional:

Nombre Ejemplo de valor Descripción

namedGraphUri http://aws.amazon.com/neptune/vocab/v01/ Gráfico DefaultNamed El gráfico predeterminado para todos los formatos RDF cuando no se especifica ningún gráfico (para formatos no QUAD y entradas NQUAD sin gráfico). El valor predeterminado es http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph

baseUri http://aws.amazon.com/neptune/default El URI base para los formatos RDF/XML y Turtle. El valor predeterminado es http://aws.amazon.com/neptune/default.

Nombre	Ejemplo de valor	Descripción
`namedGraphUri`	`http://aws.amazon.com/neptune/vocab/v01/ Gráfico DefaultNamed`	El gráfico predeterminado para todos los formatos RDF cuando no se especifica ningún gráfico (para formatos no QUAD y entradas NQUAD sin gráfico). El valor predeterminado es `http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph`
`baseUri`	`http://aws.amazon.com/neptune/default`	El URI base para los formatos RDF/XML y Turtle. El valor predeterminado es `http://aws.amazon.com/neptune/default`.
`allowEmptyStrings`	`true`	Los usuarios de Gremlin deben poder pasar valores de cadenas vacías (“”) como propiedades de nodo y borde al cargar datos CSV. Si `allowEmptyStrings` se establece en `false` (el valor predeterminado), estas cadenas vacías se tratan como nulas y no se cargan. Si `allowEmptyStrings` se establece en `true`, el programa de carga trata las cadenas vacías como valores de propiedad válidos y las carga en consecuencia.

allowEmptyStrings

true

Los usuarios de Gremlin deben poder pasar valores de cadenas vacías (“”) como propiedades de nodo y borde al cargar datos CSV. Si allowEmptyStrings se establece en false (el valor predeterminado), estas cadenas vacías se tratan como nulas y no se cargan.

Si allowEmptyStrings se establece en true, el programa de carga trata las cadenas vacías como valores de propiedad válidos y las carga en consecuencia.

Para obtener más información, consulte Gráfico predeterminado SPARQL y gráficos con nombre.

updateSingleCardinalityProperties: es un parámetro opcional que controla cómo el programa de carga masiva trata un nuevo valor para las propiedades de vértice o borde de cardinalidad única. Esto no se admite para cargar datos de openCypher (consulte Carga de datos de openCypher).

Valores permitidos: "TRUE" y "FALSE".

Valor predeterminado: "FALSE".

De forma predeterminada, o cuando updateSingleCardinalityProperties está configurado explícitamente en "FALSE", el programa de carga trata un nuevo valor como un error, porque infringe la cardinalidad única.

Por el contrario, cuando updateSingleCardinalityProperties está configurado en "TRUE", el programa de carga en bloque reemplaza el valor existente por el nuevo. Si se proporcionan varios valores de propiedades de vértices de borde o de cardinalidad única en los archivos origen que se están cargando, el valor final al terminar la carga masiva podría ser cualquiera de esos nuevos valores. El programa de carga solo garantiza que el valor existente se ha reemplazado por uno de los nuevos.
queueRequest: es un parámetro de indicador opcional que indica si la solicitud de carga se puede poner en cola o no.

No tiene que esperar a que se complete un trabajo de carga antes de emitir el siguiente, porque Neptune puede poner en cola hasta 64 trabajos a la vez, siempre que sus parámetros queueRequest estén configurados en "TRUE". El orden de espera de los trabajos será first-in-first-out (FIFO).

Si el parámetro queueRequest se omite o se establece en "FALSE", se producirá un error en la solicitud de carga si ya se está ejecutando otro trabajo de carga.

Valores permitidos: "TRUE" y "FALSE".

Valor predeterminado: "FALSE".
dependencies: se trata de un parámetro opcional que puede supeditar una solicitud de carga en cola a la finalización satisfactoria de uno o más trabajos anteriores de la cola.

Neptune puede poner en cola hasta 64 solicitudes de carga a la vez, si sus parámetros queueRequest están configurados en "TRUE". El parámetro dependencies le permite hacer que la ejecución de dicha solicitud en cola dependa de la finalización correcta de una o más solicitudes anteriores especificadas en la cola.

Por ejemplo, si las cargas Job-A y Job-B son independientes entre sí, pero la carga Job-C necesita Job-A y Job-B debe terminar antes de que comience, proceda de la siguiente manera:
1. Envíe load-job-A y load-job-B uno tras otro en cualquier orden, y guarde sus identificadores de carga.
2. Envíe load-job-C con los identificadores de carga de los dos trabajos en su campo dependencies:
```
  "dependencies" : ["job_A_load_id", "job_B_load_id"]
```
Debido al parámetro dependencies, el programa de carga en bloque no iniciará Job-C hasta que Job-A y Job-B se hayan completado correctamente. Si se produce un error en alguno de ellos, Job-C no se ejecutará y su estado se establecerá en LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

Puede configurar varios niveles de dependencia de esta manera, de modo que el error de un trabajo provoque la cancelación de todas las solicitudes que dependen directa o indirectamente de él.
userProvidedEdgeIds: este parámetro solo es necesario cuando se cargan datos de openCypher que contienen identificadores de relación. Debe incluirse y configurarse en True cuando los identificadores de relación de openCypher se proporcionen de forma explícita en los datos de carga (recomendado).

Si userProvidedEdgeIds está ausente o se establece en True, debe haber una columna :ID en todos los archivos de relaciones de la carga.

Cuando userProvidedEdgeIds está presente y se establece en False, los archivos de relaciones de la carga no deben contener ninguna columna :ID. En su lugar, el programa de carga de Neptune genera automáticamente un identificador para cada relación.

Resulta útil proporcionar los identificadores de relación de forma explícita para que el programa de carga pueda reanudar la carga una vez que se haya corregido un error en los datos CSV, sin tener que volver a cargar ninguna relación que ya se haya cargado. Si los identificadores de relación no se han asignado de forma explícita, el programa de carga no puede reanudar una carga fallida si se ha tenido que corregir algún archivo de relación y, en su lugar, debe volver a cargar todas las relaciones.
accessKey: [en desuso] un identificador de clave de acceso de un rol de IAM con acceso a los archivos de datos y al bucket de S3.

En su lugar, se recomienda el parámetro iamRoleArn. Para obtener información acerca de cómo crear un rol con acceso a Amazon S3 y, después, asociarlo a un clúster de Neptune, consulte Requisitos previos: rol de IAM y acceso a Amazon S3.

Para obtener más información, consulte Claves de acceso (ID de clave de acceso y clave de acceso secreta).
secretKey: [en desuso] en su lugar, se recomienda el parámetro iamRoleArn. Para obtener información acerca de cómo crear un rol con acceso a Amazon S3 y, después, asociarlo a un clúster de Neptune, consulte Requisitos previos: rol de IAM y acceso a Amazon S3.

Para obtener más información, consulte Claves de acceso (ID de clave de acceso y clave de acceso secreta).

Consideraciones especiales para cargar datos de openCypher

Al cargar datos de openCypher en formato CSV, el parámetro de formato debe estar establecido en opencypher.
El parámetro updateSingleCardinalityProperties no es compatible con las cargas de openCypher, porque todas las propiedades de openCypher tienen una cardinalidad única. El formato de carga de openCypher no admite matrices y, si un valor de identificador aparece más de una vez, se trata como un duplicado o un error de inserción (véase más abajo).
El programa de carga de Neptune gestiona los duplicados que encuentra en los datos de openCypher de la siguiente manera:
- Si el programa de carga encuentra varias filas con el mismo identificador de nodo, se fusionan según la siguiente regla:
  - Todas las etiquetas de las filas se añaden al nodo.
  - Para cada propiedad, solo se carga uno de los valores de la propiedad. La selección del que se va a cargar es no determinista.
- Si el programa de carga encuentra varias filas con el mismo identificador de relación, solo se carga una de ellas. La selección del que se va a cargar es no determinista.
- El programa de carga nunca actualiza los valores de las propiedades de un nodo o relación existente en la base de datos si encuentra datos de carga con el identificador del nodo o la relación existente. Sin embargo, carga etiquetas y propiedades de los nodos que no están presentes en el nodo o la relación existentes.
Aunque no es necesario asignar identificadores a las relaciones, suele ser una buena idea (consulte el parámetro userProvidedEdgeIds anterior). Sin identificadores de relación explícitos, el programa de carga debe volver a cargar todas las relaciones en caso de que se produzca un error en un archivo de relaciones, en lugar de reanudar la carga desde donde se produjo el error.

Además, si los datos de carga no contienen identificadores de relación explícitos, el programa de carga no tiene forma de detectar relaciones duplicadas.

A continuación se ofrece un ejemplo de un comando de carga de 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 respuesta del programa de carga es la misma que la normal. Por ejemplo:


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

Sintaxis de respuestas del programa de carga de Neptune


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

200 OK

Una tarea de carga que se inició correctamente devuelve el código 200.

Errores del programa de carga de Neptune

Si se produce un error, se devuelve un objeto JSON en el elemento BODY de la respuesta. El objeto message contiene una descripción del error.

Categorías de errores

Error 400: los errores de sintaxis devuelven un error de solicitud incorrecta HTTP 400. El mensaje describe el error.
Error 500: una solicitud válida que no se puede procesar devuelve un error interno del servidor HTTP 500. El mensaje describe el error.

A continuación se muestran los posibles mensajes de error del programa de carga con la descripción correspondiente.

Mensajes de error del programa de carga

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

No se encontraron las credenciales. Compruebe las credenciales suministradas con la consola o la salida de IAM. AWS CLI Asegúrese de haber añadido el rol de IAM especificado en iamRoleArn al clúster.
S3 bucket not found for source (HTTP 400)

El bucket de S3 no existe. Compruebe el nombre del bucket.
The source source-uri does not exist/not reachable (HTTP 400)

No se encontraron archivos coincidentes en el bucket de S3.
Unable to connect to S3 endpoint. Provided source = source-uri and region = aws-region (HTTP 500)

No es posible conectarse a Amazon S3. La región debe coincidir con la región del clúster. Asegúrese de que tiene un punto de enlace de la VPC. Para obtener información acerca de cómo crear un punto de enlace de la VPC, consulte Creación de un punto de conexión de VPC de Amazon S3.
Bucket is not in provided Region (aws-region) (HTTP 400)

El bucket debe estar en la misma AWS región que la instancia de base de datos de Neptune.
Unable to perform S3 list operation (HTTP 400)

La función o el usuario de IAM que se ha proporcionado no tiene permisos List en el bucket o en la carpeta. Compruebe la política o la lista de control de acceso (ACL) en el bucket.
Start new load operation not permitted on a read replica instance (HTTP 405)

La carga es una operación de escritura. Pruebe a volver a cargar en el punto de enlace del clúster de lectura/escritura.
Failed to start load because of unknown error from S3 (HTTP 500)

Amazon S3 ha devuelto un error desconocido. Póngase en contacto con AWS Support.
Invalid S3 access key (HTTP 400)

La clave de acceso no es válida. Compruebe las credenciales proporcionadas.
Invalid S3 secret key (HTTP 400)

La clave secreta no es válida. Compruebe las credenciales proporcionadas.
Max concurrent load limit breached (HTTP 400)

Si una solicitud de carga se envía sin "queueRequest" : "TRUE" y un trabajo de carga se está ejecutando actualmente, se producirá este error en la solicitud.
Failed to start new load for the source "source name". Max load task queue size limit breached. Limit is 64 (HTTP 400)

Neptune permite poner en cola hasta 64 trabajos de carga a la vez. Si se envía una solicitud de carga adicional a la cola cuando ya contiene 64 trabajos, se producirá un error en la solicitud con este mensaje.

Ejemplos del programa de carga de Neptune

ejemplo Solicitud

A continuación, se muestra una solicitud enviada mediante HTTP POST con el comando curl Carga un archivo con el formato CSV de Neptune. Para obtener más información, consulte Formato de datos de carga de 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"
    }'

ejemplo Respuesta


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

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Referencia del programa de carga

API de obtención de estado