Panduan API Penyambung CMS
Panduan API Penyambung CMS Baharu
Dokumen ini berfungsi sebagai panduan untuk melanjutkan API Penyambung CMS untuk menyokong Sistem Pengurusan Kandungan (CMS) baharu dan file jenis. Ia menggariskan proses mencipta pakej CMS baharu, mengemas kini validator dan logik pemeta, dan mengendalikan pelbagai file sambungan dan konfigurasi CMS dalam laluan `/validator` dan `penanganFileFungsi pemprosesan`. Matlamatnya adalah untuk mengekalkan seni bina modular dan agnostik CMS, membolehkan penyepaduan lancar bagi platform CMS yang berbeza dengan mengikut pendekatan berstruktur untuk pengesahan, pemprosesan dan pemetaan data.
Mencipta Pakej CMS Serupa
Suka penuh migrasi, teras tapak migrasi, migrasi-wordpress
Untuk menyokong CMS baharu (cth, Drupal), buat pakej baharu seperti ini:
TypeScript
migrasi-drupal/
Di dalamnya, laksanakan struktur yang diperlukan:
TypeScript
// migration-drupal/index.js
const pengesah = (data) => {
// Sahkan file format, struktur, medan yang diperlukan
};const EkstrakFiles = tak segerak (fileLaluan) => {
// Nyahzip atau menghuraikan kandungan
};
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
const contentTypes = {
// Takrif jenis kandungan khusus Drupal
};
const rujukan = {
// Rujukan medan khusus Drupal
};
const extractLocales = (data) => {
// Kembalikan tatasusunan setempat
};
modul.eksport = {
pengesah,
EkstrakFiles,
Jenis kandungan,
rujukan,
extractLocales
};
Di mana Ia Dipasangkan
Setelah pakej anda (cth, migration-drupal) sedia:
1. Tambahkannya ke package.json:
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
JSON
“migrasi-drupal”: “file:migration-drupal”
2. Kemas kini logik pengesah anda:
TypeScript
const { validator: drupalValidator } = memerlukan('migrasi-drupal');
suis (Pengenal CMSI) {
kes 'drupal-zip':
kembali drupalValidator({ data });
}
3. Kemas kini logik createMapper dan Tambah kes dalam suis createMapper::
TypeScript
kes 'drupal':
kembali tunggu createDrupalMapper(…);
✅ Ringkasan
Untuk menambah CMS baharu, hanya:
- Scaffold pakej seperti migration-drupal
- Ikut struktur kaedah sedia ada
- Tambahkannya pada blok suis pengesah dan pemeta
Ini mengekalkan seni bina modular dan CMS-agnostik, semua penjelasan yang disediakan dalam subTab.
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
Laluan pengesah
Laluan ini digunakan untuk mengesahkan dan memproses a file (tempatan atau daripada AWS S3), berdasarkan file jenis dan konfigurasi CMS.
✅ Berakhir Kefungsianview
- Menerima permintaan GET kepada /validator
- Menentukan jika file sumber adalah tempatan atau dari S3
- Berdasarkan kepada file sambungan:
○ Jika XML → dibaca sebagai rentetan
○ Lain (cth, ZIP) → dibaca sebagai penimbal binari - Pengendali panggilan File Memproses dengan file data
- Pada kejayaan, petakan yang diproses file menggunakan create Mapper
Tempat Menambah Sokongan untuk Baharu File Jenis
Dalam laluan ini, file sambungan ditentukan menggunakan:
JavaScript
const fileExt = fileNama?.berpecah?.('.')?.pop() ?? ”;
Kemudian berdasarkan file sambungan, logik dikendalikan seperti ini:
JavaScript
if (fileExt === 'xml') {
// Proses XML sebagai rentetan
} lain {
// Proses sebagai penimbal (cth, zip)
}
Jika anda ingin menambah yang baru file taip, anda boleh menambahnya dalam keadaan ini: Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
JavaScript
if (fileExt === 'xml') {
//…
} lain jika (fileExt === 'YourNewExtension') {
// Tambah logik untuk membaca dan mengendalikan yang baharu ini file taip
} lain {
// Pemprosesan lalai untuk binari files
}
Anda juga mungkin perlu memanjangkan pemegangFileMemproses untuk mengendalikan yang baharu file taip.
Tempat Menambah Sokongan untuk Jenis CMS Baharu
cmsType diambil daripada:
const cmsType = config?.cmsType?.toLowerCase();
Kemudian, pembolehubah ini diserahkan kepada:
data const = menunggu pemegang File Memproses (file Ext, file Data, Jenis cms, nama);
Jika anda ingin menambah CMS baharu, anda boleh memanjangkan logik di dalam pemegang File Pemprosesan atau di mana sahaja anda mengendalikan pemprosesan khusus CMS.
Kemas kini juga:
createMapper(fileLaluan, projectId, app_token, afiks, konfigurasi); Untuk menyokong jenis CMS baharu anda, tambah logik pada createMapper untuk mengendalikannya dengan sewajarnya.
✅ Ringkasan
● Anda boleh menambah baharu file sambungan dengan mengubah suai fileKeadaan tambahan Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
● Anda boleh menambah jenis CMS baharu dengan memanjangkan pemegangFileMemproses dan menciptaMapper
● Sistem sudah memisahkan pengendalian XML (rentetan) dan ZIP (penampan) — ikut struktur itu
pegang File Memproses
Dokumen ini menerangkan cara untuk mengintegrasikan platform CMS baharu ke dalam platform sedia ada file aliran pengesahan dan pemprosesan menggunakan fungsi:
● pemegangFilePemprosesan()
● pengesah()
Tujuan
Bahagian belakang pada masa ini menyokong pelbagai jenis CMS (seperti Sitecore, Contentful, WordPress, AEM). Matlamatnya adalah untuk mengesahkan dimuat naik files dan mengubahnya menjadi format berstruktur khusus untuk setiap CMS.
Sistem mengenal pasti CMS + file taip pasangan menggunakan format ini:
type-extension → cth, sitecore-zip, contentful-json, wordpress-xml
Tempat Menambah CMS Baharu
Langkah 1: Kemas kini Fungsi pengesah ().
Terletak di dalam:
JavaScript
const validator = ({ data, jenis, sambungan }: { data: sebarang; jenis: rentetan; sambungan: rentetan }) => { … }
Cari pernyataan suis pada CMSIdentifier. Setiap kes mengendalikan satu jenis CMS dan file-gabungan sambungan.
Untuk menambah CMS baharu, tambahkan kes baharu dalam blok suis ini:
Example:
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
JavaScript
kes 'newcms-json': {
kembali newCMSValidator(data); // Logik pengesahan baharu anda }
Pastikan:
● Format CMSIdentifier sepadan dengan {type}-{extension} yang dijangkakan
● Fungsi pengesahan (cth, CMSValidator baru) diimport atau ditakrifkan
Anda boleh menambah berbilang variasi, seperti:
kes 'newcms-zip':
kes 'newcms-xml':
Langkah 2: Cipta Fungsi Pengesah
Dalam projek anda, tentukan logik pengesah untuk CMS baharu. Cthample:
JavaScript
const newCMSValidator = (data) => {
// Logik pengesahan tersuai anda untuk JSON, ZIP, dsb.
kembali benar; // atau palsu jika pengesahan gagal
};
Input: Ini boleh jadi:
● Objek JSZip (untuk zip)
● Rentetan XML mentah
● objek/rentetan JSON
Output: Boolean (true = sah, false = ditolak)
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
Langkah 3: Uji dengan pemegangFilePemprosesan()
Fungsi validator() digunakan di dalam pemegangFilePemprosesan():
JavaScript
if (tunggu pengesah ({ data: zipBuffer, jenis: cmsType, sambungan: fileSambungan })) { //…
}
Pastikan pengesah CMS baharu anda dilindungi dalam keadaan dengan menghantar yang betul:
● cmsType (daripada config.cmsType)
● fileExt (daripada yang dimuat naik file)
✅ Senarai Semak Ringkasan
Penerangan Tugas
Tambah kes baharu Kemas kini blok suis validator().
Laksanakan logik Tulis fungsi CMSValidator baharu anda sendiri
Kembali
benar/salah
Pastikan pengesah mengembalikan boolean
Gunakan kekunci yang betul Ikut format sambungan jenis (cth, newcms-zip)
�� Pilihan: Petua Penyahpepijatan
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
● Log pengecam CMSI di dalam validator() untuk memastikan kes anda dicapai.
● Pastikan pemegangFilePemprosesan lulus dengan betul fileExt dan cmsType.
Menambah Sokongan Mapper untuk CMS Baharu
Selepas mengesahkan dan memproses a file, bahagian belakang menyediakan data pemetaan menggunakan fungsi createMapper. Langkah ini mengubah kandungan yang diekstrak ke dalam format piawai yang boleh digunakan untuk menjana data tiruan dan pemetaan tempat dalam CMS anda.
Cara Pemetaan Berfungsi (Aliran Aras Tinggi)
1. ✅ File berjaya disahkan dan disimpan (ZIP, XML, JSON, dll.)
2. 
Laluan ke yang diproses file ditentukan:
JavaScript
const fileLaluan = path.join(__dirname, '..', '..', 'diekstrak_files', fileNama);
3. Fungsi createMapper digunakan:
JavaScript
createMapper(fileLaluan, projectId, app_token, afiks, konfigurasi);
4. 
Fungsi ini mengarahkan logik berdasarkan jenis CMS (cth, teras tapak, contentful, wordpress)
Fungsi createMapper - Struktur
JavaScript
const createMapper = tak segerak (
fileLaluan,
projectId,
app_token,
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
imbuhan,
konfigurasi
) => {
const CMSIdentifier = config?.cmsType?.toLowerCase();
suis (Pengenal CMSI) {
kes 'sitecore':
kepulangan menanti createSitecoreMapper(fileLaluan, projectId, app_token, afiks, konfigurasi);
kes 'puas hati':
kepulangan menanti createContentfulMapper(projectId, app_token, affix, config); kes 'wordpress':
kembali createWordpressMapper(fileLaluan, projectId, app_token, afiks); lalai:
kembali palsu;
}
};
Setiap kes sepadan dengan CMS dan memanggil fungsi pemetanya.
Cara Menambah CMS Baharu
Langkah 1: Tambah Kes dalam createMapper
Tambahkan kes baharu untuk pengecam CMS anda:
JavaScript
kes 'newcms': {
kepulangan menanti createNewCMSMapper(fileLaluan, projectId, app_token, afiks, konfigurasi);
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
}
Langkah 2: Cipta Fungsi Mapper
Laksanakan fungsi baharu seperti:
JavaScript
const createNewCMSMapper = tak segerak (fileLaluan, projectId, app_token, imbuhan, konfigurasi) => {
// 1. Baca dan ubah file kandungan
// 2. Hasilkan objek pemetaan medan
// 3. Hantar ke /v2/mapper/createDummyData
// 4. Jana pemetaan setempat dan panggil /v2/migration/localeMapper };
Langkah 3: Buat Panggilan API Data Dummy
Gunakan aksios seperti pelaksanaan sedia ada:
JavaScript
const konfigurasi = {
kaedah: 'jawatan',
maxBodyLength: Infiniti,
url:
`${process.env.NODE_BACKEND_API}/v2/mapper/createDummyData/${projectId}`, tajuk: {
app_token,
'Jenis Kandungan': 'aplikasi/json'
},
data: JSON.stringify(fieldMapping),
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
};
const { data } = tunggu axios.request(config);
if (data?.data?.content_mapper?.panjang) {
deleteFolderSync(infoMap?.path);
logger.info('Kejayaan pengesahan:', {
status: HTTP_CODES?.OK,
mesej: HTTP_TEXTS?.MAPPER_SAVED,
});
}
Langkah 4: Mengendalikan Pemetaan Tempatan
Jika CMS anda menyokong penyetempatan, tambah ini atau tambah en-us sebagai lalai:
JavaScript
const mapperConfig = {
kaedah: 'jawatan',
maxBodyLength: Infiniti,
url:
`${process.env.NODE_BACKEND_API}/v2/migration/localeMapper/${projectId}`, tajuk: {
app_token,
'Jenis Kandungan': 'aplikasi/json'
},
data: {
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
tempat: Susunan.dari(localeData) ?? []
}
};
tunggu axios.request(mapperConfig);
Menjalankan muat naik-api Projek pada Mana-mana Sistem Operasi
Arahan berikut akan membimbing anda dalam menjalankan muat naik-api folder pada mana-mana sistem pengendalian, termasuk Windows dan macOS.
Memulakan muat naik-api Projek
Terdapat dua kaedah untuk memulakan muat naik-api projek:
Kaedah 1:
Jalankan arahan berikut dari direktori akar projek anda:
Shell
npm run upload
Perintah ini secara langsung akan memulakan muat naik-api pakej.
Kaedah 2:
Navigasi ke muat naik-api direktori secara manual dan jalankan pelayan pembangunan:
Shell
cd muat naik-api
npm run mula
Pendekatan ini memulakan muat naik-api dari dalam direktorinya sendiri.
Dimulakan Semula Selepas Penamatan
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
Jika projek ditamatkan secara tidak dijangka, anda boleh memulakannya semula dengan mengikuti langkah yang sama yang digariskan di atas. Pilih sama ada Kaedah 1 atau Kaedah 2 untuk melancarkan semula perkhidmatan.
Jika anda mempunyai sebarang pertanyaan, sila hubungi tso-migration@contentstack.com.
Dokumen / Sumber
 |
Panduan API Penyambung CMS CONTENTSTACK [pdf] Panduan Pengguna Panduan API Penyambung CMS, Panduan API Penyambung, Panduan API |