Perintah Loader Neptune - Amazon Neptune

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Perintah Loader Neptune

Memuat data dari bucket Amazon S3 ke instans DB Neptune.

Untuk memuat data, Anda harus mengirim permintaan POST HTTP ke titik akhir https://your-neptune-endpoint:port/loader. Parameter untuk permintaan loader dapat dikirim dalam badan POST atau sebagai parameter URL yang dikodekan.

penting

Tipe MIME harus application/json.

Bucket S3 harus berada di AWS Region yang sama dengan cluster.

catatan

Anda dapat memuat data terenkripsi dari Amazon S3 jika dienkripsi menggunakan Mode SSE-S3 Amazon S3. Dalam hal ini, Neptune dapat meniru kredensial Anda dan mengeluarkan panggilan s3:getObject atas nama Anda.

Anda juga dapat memuat data terenkripsi dari Amazon S3 yang dienkripsi menggunakan SSE-KMS, selama IAM role Anda mencakup izin yang diperlukan untuk mengakses AWS KMS. Tanpa AWS KMS izin yang tepat, operasi beban massal gagal dan mengembalikan LOAD_FAILED respons.

Neptune saat ini tidak mendukung pemuatan data yang dienkripsi Amazon S3 menggunakan Mode SSE-C.

Anda tidak perlu menunggu untuk satu pekerjaan pemuatan selesai sebelum Anda memulai satu pekerjaan lagi. Neptune dapat mengantrekan sebanyak 64 permintaan pekerjaan sekaligus, asalkan parameter queueRequest mereka semua diatur ke "TRUE". Urutan antrian pekerjaan akan menjadi first-in-first-out (FIFO). Jika Anda tidak ingin pekerjaan pemuatan diantrian, di sisi lain, Anda dapat mengatur queueRequest parameternya ke "FALSE" (default), sehingga pekerjaan pemuatan akan gagal jika yang lain sudah dalam proses.

Anda dapat menggunakan parameter dependencies untuk mengantrekan pekerjaan yang hanya harus dijalankan setelah pekerjaan sebelumnya yang ditentukan dalam antrian telah berhasil diselesaikan. Jika Anda melakukan itu dan salah satu dari mereka pekerjaan tertentu gagal, pekerjaan Anda tidak akan dijalankan dan statusnya akan diatur ke LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

Sintaks Permintaan 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"] }

Parameter Permintaan Loader Neptune

  • source — Sebuah URI Amazon S3.

    Parameter SOURCE menerima URI Amazon S3 yang mengidentifikasi satu file, beberapa file, folder, atau beberapa folder. Neptune memuat setiap file data dalam folder yang ditentukan.

    URI dapat berupa format berikut.

    • 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

    object-key-nameElemen URI setara dengan parameter awalan dalam panggilan API Amazon ListObjectsS3. Ini mengidentifikasi semua objek dalam bucket Amazon S3 yang ditentukan yang namanya dimulai dengan prefiks itu. Objek itu bisa berupa satu file atau folder, atau beberapa file dan/atau folder.

    Folder atau folder-folder yang ditentukan dapat berisi beberapa file vertex dan beberapa file edge.

    Misalnya, jika Anda memiliki struktur folder dan file berikut di bucket Amazon S3 bernama: bucket-name

    s3://bucket-name/a/bc s3://bucket-name/ab/c s3://bucket-name/ade s3://bucket-name/bcd

    Jika parameter sumber ditentukan sebagais3://bucket-name/a, tiga file pertama akan dimuat.

    s3://bucket-name/a/bc s3://bucket-name/ab/c s3://bucket-name/ade
  • format — Format data. Untuk informasi selengkapnya tentang format data untuk perintah Loader Neptune, lihat Menggunakan Amazon Neptune Bulk Loader untuk Menyerap Data.

    Nilai yang diizinkan
  • iamRoleArn — Amazon Resource Name (ARN) untuk IAM role yang akan diasumsikan oleh instans DB Neptune untuk akses ke bucket S3. Untuk informasi tentang membuat peran yang memiliki akses ke Amazon S3 dan kemudian mengaitkannya dengan klaster Neptune, lihat Prasyarat: IAM role dan Akses Amazon S3.

    Dimulai dengan rilis engine 1.2.1.0.R3, Anda juga dapat menghubungkan beberapa peran IAM jika instans DB Neptunus dan bucket Amazon S3 berada di Akun yang berbeda. AWS Dalam hal ini, iamRoleArn berisi daftar ARN peran yang dipisahkan koma, seperti yang dijelaskan dalam. Merantai peran IAM di Amazon Neptunus Sebagai contoh:

    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" }'
  • regionregion Parameter harus cocok dengan AWS Wilayah cluster dan bucket S3.

    Amazon Neptune tersedia di Wilayah berikut:

    • US East (N. Virginia):   us-east-1

    • AS Timur (Ohio): us-east-2

    • US West (N. California):   us-west-1

    • US West (Oregon):   us-west-2

    • Canada (Central):   ca-central-1

    • South America (São Paulo):   sa-east-1

    • Eropa (Stockholm): eu-north-1

    • Eropa (Irlandia): eu-west-1

    • Eropa (London): eu-west-2

    • Eropa (Paris): eu-west-3

    • Eropa (Frankfurt): eu-central-1

    • Timur Tengah (Bahrain): me-south-1

    • Timur Tengah (UEA): me-central-1

    • Israel (Tel Aviv): il-central-1

    • Afrika (Cape Town): af-south-1

    • Asia Pasifik (Hong Kong): ap-east-1

    • Asia Pacific (Tokyo):   ap-northeast-1

    • Asia Pasifik (Seoul): ap-northeast-2

    • Asia Pasifik (Osaka): ap-northeast-3

    • Asia Pacific (Singapore):   ap-southeast-1

    • Asia Pacific (Sydney):   ap-southeast-2

    • Asia Pasifik (Mumbai): ap-south-1

    • Tiongkok (Beijing): cn-north-1

    • Tiongkok (Ningxia): cn-northwest-1

    • AWS GovCloud (AS-Barat): us-gov-west-1

    • AWS GovCloud (AS-Timur): us-gov-east-1

  • mode — Mode pekerjaan pemuatan.

    Nilai yang diizinkan:RESUME,NEW,AUTO.

    Nilai default: AUTO

    • RESUME — Dalam mode RESUME, loader mencari pemuatan sebelumnya dari sumber ini, dan jika menemukan satu, melanjutkan pekerjaan pemuatan tersebut. Jika tidak ada pekerjaan pemuatan sebelumnya yang ditemukan, loader berhenti.

      Loader menghindari memuat ulang file yang berhasil dimuat di pekerjaan sebelumnya. Ia hanya mencoba untuk memproses file yang gagal. Jika Anda menjatuhkan data yang dimuat sebelumnya dari klaster Neptune Anda, data tersebut tidak dimuat ulang dalam mode ini. Jika pekerjaan pemuatan sebelumnya berhasil memuat semua file dari sumber yang sama, tidak ada yang dimuat ulang, dan loader mengembalikan keberhasilan.

    • NEW — Dalam mode NEW, it menciptakan permintaan pemuatan baru terlepas dari pemuatan sebelumnya. Anda dapat menggunakan mode ini untuk memuat ulang semua data dari sumber setelah menjatuhkan data yang dimuat sebelumnya dari klaster Neptune Anda, atau untuk memuat data baru yang tersedia di sumber yang sama.

    • AUTO — Dalam mode AUTO, loader mencari pekerjaan pemuatan sebelumnya dari sumber yang sama, dan jika menemukannya, melanjutkan pekerjaan itu, seperti pada mode RESUME.

      Jika loader tidak menemukan pekerjaan pemuatan sebelumnya dari sumber yang sama, loader akan memuat semua data dari sumbernya, seperti pada mode NEW.

  • failOnError — Sebuah bendera untuk mengubah berhenti penuh pada kesalahan.

    Nilai yang diizinkan: "TRUE", "FALSE".

    Nilai default:"TRUE".

    Ketika parameter ini diatur ke "FALSE", loader mencoba memuat semua data di lokasi yang ditentukan, melewatkan entri apa pun yang memiliki kesalahan.

    Ketika parameter ini diatur ke "TRUE", loader berhenti segera setelah menemukan kesalahan. Data yang dimuat sampai saat itu tetap ada.

  • parallelism — Ini adalah parameter opsional yang dapat diatur untuk mengurangi jumlah utas yang digunakan oleh proses pemuatan massal.

    Nilai yang diizinkan:

    • LOW — Jumlah utas yang digunakan adalah jumlah vCPU yang tersedia dibagi dengan 8.

    • MEDIUM — Jumlah utas yang digunakan adalah jumlah vCPU yang tersedia dibagi dengan 2.

    • HIGH — Jumlah utas yang digunakan sama dengan jumlah vCPU yang tersedia.

    • OVERSUBSCRIBE — Jumlah utas yang digunakan adalah jumlah vCPU yang tersedia dikali dengan 2. Jika nilai ini digunakan, loader massal mengambil semua sumber daya yang tersedia.

      Ini tidak berarti, bagaimanapun, bahwa pengaturan OVERSUBSCRIBE menghasilkan 100% utilisasi CPU. Karena operasi pemuatan terikat I/O, utilisasi CPU tertinggi yang diharapkan adalah dalam kisaran 60% hingga 70%.

    Nilai default: HIGH

    parallelismPengaturan terkadang dapat mengakibatkan kebuntuan antar utas saat memuat data OpenCypher. Ketika ini terjadi, Neptunus mengembalikan kesalahan. LOAD_DATA_DEADLOCK Anda biasanya dapat memperbaiki masalah dengan mengatur parallelism ke pengaturan yang lebih rendah dan mencoba kembali perintah load.

  • parserConfiguration — Sebuah objek opsional dengan nilai konfigurasi parser tambahan. Masing-masing parameter turunan juga opsional:

    Nama Nilai Contoh Deskripsi
    namedGraphUri http://aws.amazon.com/neptune/vocab/v01/ DefaultNamed Grafik Grafik default untuk semua format RDF ketika tidak ada grafik yang ditentukan (untuk format non-quads dan entri NQUAD tanpa grafik). Bawaannya adalah http://aws.amazon.com/neptune/vocab/v01/DefaultNamedGraph
    baseUri http://aws.amazon.com/neptune/default URI dasar untuk format RDF/XHTML dan Turtle. Nilai default-nya http://aws.amazon.com/neptune/default.
    allowEmptyStrings benar

    Pengguna Gremlin harus dapat melewatkan nilai string kosong (“”) sebagai properti node dan edge saat memuat data CSV. Jika allowEmptyStrings diatur ke false (default), string kosong diperlakukan sebagai null dan tidak dimuat.

    Jika allowEmptyStrings diatur ke true, loader memperlakukan string kosong sebagai nilai properti yang valid dan memuatnya sesuai keperluan.

    Untuk informasi selengkapnya, lihat Grafik Standar SPARQL dan Grafik Bernama.

  • updateSingleCardinalityProperties — Ini adalah parameter opsional yang mengontrol bagaimana bulk loader memperlakukan nilai baru untuk properti vertex atau edge single-cardinality. Ini tidak didukung untuk memuat data OpenCypher (lihat). Memuat data OpenCypher

    Nilai yang diizinkan: "TRUE", "FALSE".

    Nilai default:"FALSE".

    Secara default, atau saat updateSingleCardinalityProperties secara eksplisit diatur ke "FALSE", loader memperlakukan nilai baru sebagai kesalahan, karena melanggar kardinalitas tunggal.

    Saat updateSingleCardinalityProperties diatur ke "TRUE", di sisi lain, loader massal menggantikan nilai yang ada dengan yang baru. Jika beberapa edge atau nilai properti vertex single-cardinality disediakan dalam file sumber yang dimuat, nilai akhir pada akhir pemuatan massal bisa menjadi salah satu dari nilai-nilai baru tersebut. Loader hanya menjamin bahwa nilai yang ada telah digantikan oleh salah satu yang baru.

  • queueRequest — Ini adalah parameter bendera opsional yang menunjukkan apakah permintaan pemuatan dapat diantrekan atau tidak.

    Anda tidak perlu menunggu satu pekerjaan muat selesai sebelum mengeluarkan pekerjaan berikutnya, karena Neptune dapat mengantrekan sebanyak 64 pekerjaan sekaligus, asalkan parameter queueRequest semua diatur ke "TRUE". Urutan antrian pekerjaan akan menjadi first-in-first-out (FIFO).

    Jika parameter queueRequest dihilangkan atau diatur ke "FALSE", permintaan pemuatan akan gagal jika pekerjaan pemuatan lain sudah berjalan.

    Nilai yang diizinkan: "TRUE", "FALSE".

    Nilai default:"FALSE".

  • dependencies — Ini adalah parameter opsional yang dapat membuat permintaan pemuatan yang mengantre bergantung pada penyelesaian yang berhasil dari satu atau lebih pekerjaan sebelumnya dalam antrean.

    Neptune dapat mengantrekan sebanyak 64 permintaan pemuatan sekaligus, jika parameter queueRequest permintaannya diatur ke "TRUE". Parameter dependencies memungkinkan Anda melakukan eksekusi seperti permintaan mengantre yang tergantung pada penyelesaian yang berhasil dari satu atau lebih permintaan ditentukan sebelumnya dalam antrean.

    Misalnya, jika pemuatan Job-A dan Job-B independen satu sama lain, namun pemuatan Job-C membutuhkan Job-A dan Job-B harus selesai sebelum dimulai, lanjutkan sebagai berikut:

    1. Kirim load-job-A dan load-job-B satu demi satu dalam urutan apa pun, dan simpan load-id mereka.

    2. Kirim load-job-C dengan load-id dari dua pekerjaan di bidang dependencies-nya:

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

    Karena parameter dependencies, loader massal tidak akan memulai Job-C sampai Job-A dan Job-B telah berhasil diselesaikan. Jika salah satu dari mereka gagal, Job-C tidak akan dieksekusi, dan statusnya akan diatur ke LOAD_FAILED_BECAUSE_DEPENDENCY_NOT_SATISFIED.

    Anda dapat mengatur beberapa tingkat ketergantungan dengan cara ini, sehingga kegagalan satu pekerjaan akan menyebabkan semua permintaan yang secara langsung atau tidak langsung tergantung padanya untuk dibatalkan.

  • userProvidedEdgeIds- Parameter ini diperlukan hanya saat memuat data OpenCypher yang berisi ID hubungan. Itu harus disertakan dan disetel ke True saat ID hubungan OpenCypher secara eksplisit disediakan dalam data pemuatan (disarankan).

    Ketika tidak userProvidedEdgeIds ada atau diatur keTrue, :ID kolom harus ada di setiap file hubungan dalam beban.

    Ketika userProvidedEdgeIds hadir dan diatur keFalse, file hubungan dalam beban tidak boleh berisi :ID kolom. Sebagai gantinya, pemuat Neptunus secara otomatis menghasilkan ID untuk setiap hubungan.

    Ini berguna untuk memberikan ID hubungan secara eksplisit sehingga loader dapat melanjutkan pemuatan setelah kesalahan dalam data CSV telah diperbaiki, tanpa harus memuat ulang hubungan apa pun yang telah dimuat. Jika ID hubungan belum ditetapkan secara eksplisit, loader tidak dapat melanjutkan pemuatan yang gagal jika ada file hubungan yang harus diperbaiki, dan sebagai gantinya harus memuat ulang semua hubungan.

  • accessKey[usang] Access key ID dari IAM role dengan akses ke bucket S3 dan file data.

    Parameter iamRoleArn dianjurkan sebagai gantinya. Untuk informasi tentang membuat peran yang memiliki akses ke Amazon S3 dan kemudian mengaitkannya dengan klaster Neptune, lihat Prasyarat: IAM role dan Akses Amazon S3.

    Untuk informasi lebih lanjut, lihat Access key (access key ID dan secret access key).

  • secretKey   –   [usang] Parameter iamRoleArn dianjurkan sebagai gantinya. Untuk informasi tentang membuat peran yang memiliki akses ke Amazon S3 dan kemudian mengaitkannya dengan klaster Neptune, lihat Prasyarat: IAM role dan Akses Amazon S3.

    Untuk informasi lebih lanjut, lihat Access key (access key ID dan secret access key).

Pertimbangan khusus untuk memuat data OpenCypher

  • Saat memuat data OpenCypher dalam format CSV, parameter format harus diatur ke. opencypher

  • updateSingleCardinalityPropertiesParameter tidak didukung untuk beban OpenCypher karena semua properti OpenCypher memiliki kardinalitas tunggal. Format beban OpenCypher tidak mendukung array, dan jika nilai ID muncul lebih dari sekali, itu diperlakukan sebagai duplikat atau kesalahan penyisipan (lihat di bawah).

  • Pemuat Neptunus menangani duplikat yang ditemuinya dalam data OpenCypher sebagai berikut:

    • Jika loader menemukan beberapa baris dengan ID node yang sama, mereka digabungkan menggunakan aturan berikut:

      • Semua label di baris ditambahkan ke node.

      • Untuk setiap properti, hanya satu dari nilai properti yang dimuat. Pemilihan yang akan dimuat adalah non-deterministik.

    • Jika loader menemukan beberapa baris dengan ID hubungan yang sama, hanya satu dari mereka yang dimuat. Pemilihan yang akan dimuat adalah non-deterministric.

    • Loader tidak pernah memperbarui nilai properti dari node atau relasi yang ada dalam database jika menemukan data beban yang memiliki ID dari node atau relasi yang ada. Namun, itu memuat label node dan properti yang tidak ada di node atau hubungan yang ada.

  • Meskipun Anda tidak harus menetapkan ID ke hubungan, biasanya ide yang bagus (lihat userProvidedEdgeIds parameter di atas). Tanpa ID hubungan eksplisit, pemuat harus memuat ulang semua hubungan jika terjadi kesalahan dalam file relasi, daripada melanjutkan pemuatan dari tempat gagal.

    Selain itu, jika data pemuatan tidak berisi ID hubungan eksplisit, loader tidak memiliki cara untuk mendeteksi hubungan duplikat.

Berikut adalah contoh perintah beban 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", }'

Respons loader sama dengan normal. Sebagai contoh:

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

Sintaks Respons Loader Neptune

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

Pekerjaan pemuatan yang berhasil dimulai mengembalikan kode 200.

Kesalahan Loader Neptune

Ketika terjadi kesalahan, objek JSON dikembalikan dalam BODY respons. Objek message berisi deskripsi kesalahan.

Kategori Kesalahan
  • Error 400 - kesalahan Sintaks mengembalikan kesalahan permintaan buruk HTTP 400. Pesan ini menjelaskan kesalahan.

  • Error 500 — Permintaan valid yang tidak dapat diproses mengembalikan HTTP 500 kesalahan server internal. Pesan ini menjelaskan kesalahan.

Berikut ini adalah kemungkinan pesan kesalahan dari loader dengan deskripsi kesalahannya.

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

    Kredensialnya tidak ditemukan. Verifikasi kredensyal yang disediakan terhadap konsol atau output IAM. AWS CLI Pastikan Anda telah menambahkan peran IAM yang ditentukan iamRoleArn ke dalam cluster.

  • S3 bucket not found for source (HTTP 400)

    Bucket S3 tidak ada. Periksa nama bucket.

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

    File yang cocok tidak ditemukan di bucket S3.

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

    Tidak dapat terhubung ke Amazon S3. Wilayah harus sesuai dengan Wilayah klaster. Pastikan bahwa Anda memiliki VPC Endpoint. Untuk informasi tentang cara membuat VPC Endpoint, lihat Membuat VPC Endpoint Amazon S3.

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

    Bucket harus berada di AWS Wilayah yang sama dengan instans DB Neptunus Anda.

  • Unable to perform S3 list operation (HTTP 400)

    Pengguna atau IAM role tidak memiliki izin List pada bucket atau folder. Periksa kebijakan atau daftar kontrol akses (ACL) di bucket.

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

    Memuat adalah operasi menulis. Coba lagi pemuatan pada titik akhir klaster baca/tulis.

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

    Amazon S3 mengembalikan kesalahan yang tidak diketahui. Hubungi AWS Support.

  • Invalid S3 access key (HTTP 400)

    Access key tidak valid. Periksa kredensial yang disediakan.

  • Invalid S3 secret key (HTTP 400)

    Kunci rahasia tidak valid. Periksa kredensial yang disediakan.

  • Max concurrent load limit breached (HTTP 400)

    Jika permintaan pemuatan diajukan tanpa "queueRequest" : "TRUE", dan pekerjaan pemuatan saat ini berjalan, permintaan akan gagal dengan kesalahan ini.

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

    Neptune mendukung antrean sebanyak 64 pekerjaan loader sekaligus. Jika permintaan pemuatan tambahan diserahkan ke antrean ketika sudah berisi 64 pekerjaan, permintaan gagal dengan pesan ini.

Contoh Neptune Loader

contoh Permintaan

Berikut ini adalah permintaan yang dikirim melalui HTTP POST menggunakan perintah curl. Permintaan tersebut memuatkan file dalam format CSV Neptune. Untuk informasi selengkapnya, lihat Format data muat 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" }'
contoh Respons
{ "status" : "200 OK", "payload" : { "loadId" : "ef478d76-d9da-4d94-8ff1-08d9d4863aa5" } }