Guia da API do Conector CMS
Novo guia da API do conector CMS
Este documento serve como um guia para estender a API do Conector CMS para suportar novos Sistemas de Gerenciamento de Conteúdo (CMS) e file tipos. Descreve o processo de criação de novos pacotes CMS, atualização da lógica de validação e mapeamento e tratamento de vários file extensões e configurações de CMS na rota `/validator` e `handle`FileFunção de processamento. O objetivo é manter uma arquitetura modular e independente de CMS, permitindo a integração perfeita de diferentes plataformas de CMS, seguindo uma abordagem estruturada para validação, processamento e mapeamento de dados.
Criando um pacote CMS semelhante
Como conteúdo de migração, migração-sitecore, migração-wordpress
Para dar suporte a um novo CMS (por exemplo, Drupal), crie um novo pacote como este:
TypeScript
migração-drupal/
Dentro dele, implemente a estrutura necessária:
TypeScript
// migration-drupal/index.js
constante validador = (dados) => {
// Validar file formato, estrutura, campos obrigatórios
};constante ExtrairFiles = async (fileCaminho) => {
// Descompactar ou analisar conteúdo
};
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
constante contentTypes = {
// Definições de tipos de conteúdo específicos do Drupal
};
constante referência = {
// Referências de campos específicos do Drupal
};
constante extrairLocais = (dados) => {
// Retorna o array de localidades
};
módulo.exports = {
validador,
ExtrairFiles,
tipos de conteúdo,
referência,
extrairLocais
};
Onde está conectado
Assim que seu pacote (por exemplo, migration-drupal) estiver pronto:
1. Adicione-o ao package.json:
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
JSON
“migração-drupal”: “file:migração-drupal”
2. Atualize a lógica do seu validador:
TypeScript
constante { validator: drupalValidator } = requerer('migração-drupal');
trocar (CMSIdentifier) {
caso 'drupal-zip':
retornar drupalValidator({ dados });
}
3. Atualize a lógica do createMapper e adicione o caso no switch do createMapper::
TypeScript
caso 'drupal':
retornar aguardar createDrupalMapper(…);
✅ Resumo
Para adicionar um novo CMS, basta:
- Crie um pacote semelhante ao migration-drupal.
- Siga a estrutura do método existente
- Adicione-o aos blocos de seleção do validador e do mapeador.
Isso mantém a arquitetura modular e independente de CMS, todas as explicações fornecidas em subabas.
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
Rota do validador
Esta rota é usada para validar e processar um file (local ou do AWS S3), com base em file tipo e configuração do CMS.
✅ Funcionalidade encerradaview
- Aceita uma solicitação GET para /validator
- Determina se o file A fonte é local ou do S3.
- Com base no file extensão:
○ Se XML → lê como string
○ Caso contrário (ex.: ZIP) → lê como buffer binário - Atendimento de chamadas File Processando com file dados
- Em caso de sucesso, mapeia o processado. file usando o mapeador de criação
Onde adicionar suporte para novos File Tipos
Neste percurso, file As extensões são determinadas usando:
JavaScript
constante fileExt = fileNome?.dividir?.('.')?.pop() ?? ";
Então, com base em file A extensão, a lógica é tratada da seguinte forma:
JavaScript
if (fileExt === 'xml') {
// Processar XML como string
} outro {
// Processar como buffer (ex: compactar em zip)
}
Se você quiser adicionar um novo file Você pode adicionar esse tipo de informação dentro desta condição: Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
JavaScript
if (fileExt === 'xml') {
// …
} senão se (fileExt === 'suaNovaExtensão') {
// Adicione lógica para ler e lidar com este novo file tipo
} outro {
// Processamento padrão para binário files
}
Você também pode precisar estender a alça.FileProcessamento para lidar com o novo file tipo.
Onde adicionar suporte para novos tipos de CMS
O cmsType é obtido de:
const cmsType = config?.cmsType?.toLowerCase();
Posteriormente, essa variável é passada para:
const data = aguardar handle File Processamento (file Ext, file Dados, tipo CMS, nome);
Se você quiser adicionar um novo CMS, pode estender a lógica dentro do manipulador. File Processamento ou qualquer outro local onde você lide com processamento específico do CMS.
Atualize também:
criarMapeador(fileCaminho, idDoProjeto, tokenDoAplicativo, afixo, configuração); Para dar suporte ao seu novo tipo de CMS, adicione lógica ao createMapper para lidar com ele adequadamente.
✅ Resumo
● Você pode adicionar novos file extensões modificando o fileCondição externa Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
● Você pode adicionar novos tipos de CMS estendendo o identificador.FileProcessamento e criação do mapeador
● O sistema já separa o tratamento de XML (string) e ZIP (buffer) — siga essa estrutura.
Lidar File Processamento
Este documento explica como integrar uma nova plataforma CMS a um sistema já existente. file Fluxo de validação e processamento usando as funções:
● alçaFileProcessamento()
● validador()
Propósito
O backend atualmente suporta vários tipos de CMS (como Sitecore, Contentful, WordPress, AEM). O objetivo é validar os arquivos enviados. filee transformá-los em um formato estruturado específico para cada CMS.
O sistema identifica um CMS + file digite o par usando este formato:
extensão-de-tipo → por exemplo, sitecore-zip, contentful-json, wordpress-xml
Onde adicionar um novo CMS
Passo 1: Atualize a função validadora ()
Localizado no interior:
JavaScript
constante validador = ({ dados, tipo, extensão }: { dados: qualquer; tipo: string; extensão: string }) => { … }
Localize a instrução switch em CMSIdentifier. Cada caso trata de um tipo de CMS e file- combinação de extensão.
Para adicionar um novo CMS, adicione um novo caso neste bloco de seleção:
Exampem:
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
JavaScript
caso 'newcms-json': {
retornar novoCMSValidador(dados); // Sua nova lógica de validação }
Certificar-se:
● O formato do CMSIdentifier corresponde ao esperado {tipo}-{extensão}
● A função de validação (por exemplo, newCMSValidator) é importada ou definida.
Você pode adicionar várias variações, como:
caso 'newcms-zip':
caso 'newcms-xml':
Etapa 2: Criar a função de validação
No seu projeto, defina a lógica de validação para o novo CMS. Exemplo:ampem:
JavaScript
constante novoCMSValidador = (dados) => {
// Sua lógica de validação personalizada para JSON, ZIP, etc.
retornar verdadeiro; // ou falso se a validação falhar
};
Entrada: Isto poderia ser:
● Um objeto JSZip (para compactação)
● String XML bruta
● Objeto/string JSON
Saída: Booleano (verdadeiro = válido, falso = rejeitado)
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
Passo 3: Teste com a alçaFileProcessamento()
A função validator() é usada dentro do handle.FileProcessamento():
JavaScript
if (aguardar validador({ dados: zipBuffer, tipo: cmsType, extensão: fileExt })) { // …
}
Certifique-se de que seu novo validador de CMS atenda à condição, passando o seguinte parâmetro corretamente:
● cmsType (de config.cmsType)
● fileExt (do arquivo carregado) file)
✅ Lista de verificação resumida
Descrição da tarefa
Adicionar novo caso Atualizar bloco switch validator()
Implemente a lógica. Escreva sua própria função `newCMSValidator`.
Retornar
verdadeiro/falso
Garantir que o validador retorne um valor booleano.
Use a chave correta. Siga o formato tipo-extensão (ex.: newcms-zip).
�� Opcional: Dicas de depuração
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
● Registre o CMSIdentifier dentro de validator() para garantir que seu caso seja alcançado.
● Certifique-se de que a alça esteja firme.FileO processamento está passando corretamente. fileExt e cmsType.
Adicionando suporte a mapas para um novo CMS
Após validar e processar um fileO backend prepara os dados de mapeamento usando a função createMapper. Esta etapa transforma o conteúdo extraído em um formato padronizado que pode ser usado para gerar dados fictícios e mapeamentos de localidade no seu CMS.
Como funciona o mapeamento (fluxograma de alto nível)
1. ✅ File foi validado e salvo com sucesso (ZIP, XML, JSON, etc.)
2. 
Caminho para o processado file está determinado:
JavaScript
constante fileCaminho = caminho.join(__dirname, '..', '..', 'extraído_fileé, fileNome);
3. A função createMapper é invocada:
JavaScript
criarMapeador(fileCaminho, idDoProjeto, tokenDoAplicativo, afixo, configuração);
4. 
Essa função encaminha a lógica com base no tipo de CMS (por exemplo, Sitecore, Contentful, WordPress).
Função createMapper – Estrutura
JavaScript
constante criarMapeador = assíncrono (
fileCaminho,
ID do projeto,
token_do_aplicativo,
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
afixo,
configuração
) => {
constante CMSIdentifier = config?.cmsType?.toLowerCase();
trocar (CMSIdentifier) {
caso 'sitecore':
retornar aguardar criarMapeadorSitecore(fileCaminho, idDoProjeto, tokenDoAplicativo, afixo, configuração);
caso 'contente':
retornar aguardar criarMapeadorDeConteúdo(projectId, app_token, affix, config); caso 'wordpress':
retornar criarMapeadorWordpress(fileCaminho, idDoProjeto, tokenDoAplicativo, afixo); padrão:
retornar falso;
}
};
Cada caso corresponde a um CMS e chama sua função de mapeamento.
Como adicionar um novo CMS
Passo 1: Adicione um caso em createMapper
Adicione um novo caso para o seu identificador CMS:
JavaScript
caso 'novoscms': {
retornar aguardar criarNovoMapaCMS(fileCaminho, idDoProjeto, tokenDoAplicativo, afixo, configuração);
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
}
Etapa 2: Criar a função de mapeamento
Implemente uma nova função como:
JavaScript
constante criarNovoMapaCMS = assíncrono (fileCaminho, idDoProjeto, tokenDoAplicativo, afixo, configuração) => {
// 1. Ler e transformar file conteúdo
// 2. Gerar objeto de mapeamento de campos
// 3. Enviar para /v2/mapper/createDummyData
// 4. Gere o mapeamento de localidade e chame /v2/migration/localeMapper };
Etapa 3: Faça uma chamada de API com dados fictícios
Utilize o axios da mesma forma que na implementação existente:
JavaScript
constante config = {
método: 'publicar',
comprimento máximo do corpo: Infinidade,
url:
`${process.env.NODE_BACKEND_API}/v2/mapper/createDummyData/${projectId}`, cabeçalhos: {
token_do_aplicativo,
'Tipo de conteúdo': 'application/json'
},
dados: JSON.stringify(fieldMapping),
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
};
constante { dados } = aguardar axios.request(config);
if (dados?.dados?.mapeador_de_conteúdo?.comprimento) {
excluirPastaSync(infoMap?.path);
logger.info('Validação concluída com sucesso:', {
status: HTTP_CODES?.OK,
mensagem: HTTP_TEXTS?.MAPPER_SAVED,
});
}
Etapa 4: Mapeamento de localização de gerenciamento
Se o seu CMS suporta localização, adicione isso ou defina en-us como padrão:
JavaScript
constante mapperConfig = {
método: 'publicar',
comprimento máximo do corpo: Infinidade,
url:
`${process.env.NODE_BACKEND_API}/v2/migration/localeMapper/${projectId}`, cabeçalhos: {
token_do_aplicativo,
'Tipo de conteúdo': 'application/json'
},
dados: {
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
localidade: Variedade.from(localeData) ?? []
}
};
aguardar axios.request(mapperConfig);
Executando o API de upload Projete em qualquer sistema operacional
As instruções a seguir irão orientá-lo na execução do API de upload pasta em qualquer sistema operacional, incluindo Windows e macOS.
Iniciando o API de upload Projeto
Existem dois métodos para iniciar o API de upload projeto:
Método 1:
Execute o seguinte comando a partir do diretório raiz do seu projeto:
Concha
npm run upload
Este comando iniciará diretamente o API de upload pacote.
Método 2:
Navegue até o API de upload Crie o diretório manualmente e execute o servidor de desenvolvimento:
Concha
cd API de upload
npm run start
Essa abordagem inicia o API de upload de dentro de seu próprio diretório.
Reiniciar após o encerramento
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
Se o projeto for encerrado inesperadamente, você poderá reiniciá-lo seguindo os mesmos passos descritos acima. Escolha o Método 1 ou o Método 2 para reiniciar o serviço.
Se você tiver alguma dúvida, entre em contato com tso-migration@contentstack.com.
Documentos / Recursos
 |
Guia da API do Conector CMS CONTENTSTACK [pdf] Guia do Usuário Guia da API do Conector CMS, Guia da API do Conector, Guia da API |