Integrações Yapoli – Central de atendimento Yapoli

A Yapoli é uma plataforma de gestão e distribuição de ativos digitais pensada para a indústria 4.0.

Por isso sua missão é se integrar no ecossistema do cliente, cumprindo sua missão de prover
governança dos ativos digitais provendo um conjunto de serviços para se integrar a este
ecossistema.

Para operacionalizar essas interações, na Yapoli é possível configurar integrações. Cada integração
tem uma finalidade específica e possui critérios de permissão e escopo que delimitam sua atuação
dentro da plataforma.

A Yapoli atualmente suporta 2 tipos de processos de integração:

Distribuição de assets.
Importação de assets e automação.

Para suportar os processos de negócio a Yapoli tem os seguintes pontos de entrada:

API: Fornece uma API por onde é possível, dentro do escopo determinado, consultar itens e
seus respectivos metadados e arquivos.
Importação via S3: Fornece parâmetros para importação direto no S3 de assets para plataforma

E de saída:

Webhook (ou mensageria):
- Ativo: A partir de eventos predeterminados, a Yapoli pode disparar um serviço
  específico, enviando dados relevantes ao contexto do evento determinado.
- Passivo: A Yapoli pode receber mensagens de notificação de alteração de dados em
  itens.
Distribuição: Dentro do escopo de uma integração, a Yapoli publica os arquivos para consumo por outras aplicações com acesso restrito ou para CDNs com acesso público.

PS: A Yapoli é uma plataforma em rápida e constante evolução. Essas funcionalidades certamente se expandirão e englobarão mais eventos, dados e serviços futuramente

Contexto e escopo da integração:

Cada integração se aplica a um contexto predeterminado. O escopo delimita sobre quais itens e assets uma integração se aplica a partir de um filtro predeterminado. Dessa forma, é possível ter diversas integrações diferentes (com escopos e funcionalidades diferentes).

Detalhamos abaixo as especificações técnicas de cada serviço, considerando sempre que todos operam no contexto de uma integração. Para configurá-los na plataforma, entre em contato com nossa equipe de atendimento.

Pontos de integração de entrada

API
- A documentação da API da Yapoli pode ser consultada em: https://documenter.getpostman.com/view/7711620/UVeJM5pk#intro

Importação via S3

Para importações de arquivos em lote, a Yapoli disponibiliza acesso ao seu repositório S3, a partir de onde capturamos os arquivos e os transformamos em assets na plataforma. Caso tenha uma automação configurada, o asset inicia então o processo de automação para criar um item direto. Caso não tenha automação ou dê qualquer erro, então o asset vai para o bucket na plataforma. Para que o asset siga para a automação é importante que ele respeite as regras de automação, seja na estruturação do nome de acordo com a expressão regular correspondente ou pela definição dos campos exif apropriados.

Para fazer importação via S3 é necessário estar de posse de um conjunto de credenciais Access key e secret key emitidos pela Yapoli. Para isso, é necessário executar o endpoint Parâmetros para upload. O endpoint então retornará o bucket e as credenciais que devem ser usadas. Em posse disse deve-se utilizar o AWS CLI, AWS SDK ou AWS API para fazer upload dos arquivos no bucket designado.

Pontos de integração de saída

Webhook

A Yapoli pode disparar serviços no modelo webhook, assim que um evento relevante ocorra na plataforma. Por enquanto nós suportamos dois tipos de eventos:

Asset criado; e
Item atualizado.

Na ocorrência do evento configurado é chamado o endpoint cadastrado informando os dados relevantes decorrentes daquele evento. Os serviços que são chamados devem ser endpoints HTTP REST para os quais é possível especificar os seguintes dados:

Método: GET ou POST;
Endpoint: Uma URL que recebe e retorna dados em JSON e dá respostas seguindo o padrão REST. Se utilizar parâmetros dinâmicos os valores devem ser especificados como um parâmetro de query string com as chaves {KEY1}, {KEY2}, etc. Exemplo: https:://endpoint.client.com?chave1={KEY1}&chave2={KEY2} ;
Authorization: dados para autenticação da API, respeitando o padrão OAuth e OAuth v2. É possível especificar cabeçalhos e um “payload” específico para essa chamada, bem como determinar qual o path do retorno a ser obtido. Se não informado as credenciais de acesso deve estar nos cabeçalhos. PS: as credenciais de acesso aos serviços ficam armazenadas num serviço de armazenamento de segredos (AWS Secrets Manager);
Headers: Os cabeçalhos da requisição;
Response Path: Path da resposta a ser obtido;
Indicação se deve levar os parâmetros do evento;

O retorno das chamadas de webhook, quando devem ser tratadas, devem retornar somente um registro (especificado pelo “response path”).

Tratamento de erros

Os erros que ocorrerem serão notificados à equipe de suporte e operações da Yapoli que atuará no caso. Na ocasião de haver uma falha no endpoint / serviço cadastrada o responsável técnico do cliente será acionado. Por isso, é necessário informar um contato técnico para cada webhook cadastrado.

Distribuição

As integrações podem ser cadastradas para fazer a distribuição dos itens / assets configurados na integração para um storage específico para ser consumido diretamente com autorização via API ou por um CDN. Além do storage específico, os arquivos são publicados com uma taxonomia determinada, gerando assim, URLs relevantes e pesquisáveis. Além disso é possível definir para os assets distribuídos uma receita com a definição de parâmetros específicos para os arquivos a serem distribuídos, ex: compactação, formatação, etc.

Para configurar uma distribuição com disponibilidade pública via CDN é necessário informar a URL pública para a qual os arquivos serão publicados. Ela deve ser informada para que a URL do asset publicado na CDN seja informada na API.

Os arquivos serão atualizados a cada ocorrência que altere ou o conteúdo dos arquivos de um item ou sua taxonomia e, consequentemente, o nome dos arquivos.

Processos de integração

Distribuição de assets

A distribuição de assets é feita a partir de uma integração configurada. Além disso, deve ser definido o escopo da aplicação, que é o filtro que define os itens para os quais a distribuição deve ser feita. Por enquanto os filtros suportam os seguintes parâmetros, que podem ser combinados:

Categoria;
Segmento;
Tags

Uma vez definidos filtros e os parâmetros, os assets dos itens começarão a ser distribuídos, com os nomes dos arquivos respeitando a estrutura da taxonomia definida para os itens. Para consultar os itens distribuídos e os arquivos correspondentes, deve-se utilizar o endpoint de Lista de itens distribuídos. Somente através deste endpoint é possível ter segurança de quais arquivos e quais os nomes dos arquivos foram gerados. Isso é importante devido à estrutura da taxonomia ser dinâmica e poder ser alterada por usuários com a autorização devida na plataforma.

Para ser notificado das atualizações em itens e seus efeitos na distribuição assim que elas acontecem, é possível registrar um webhook no evento item atualizado. A estrutura de dados é igual à retornada no endpoint de lista de itens distribuídos.

No caso de distribuições privadas que não serão publicadas para CDN público, as URLs informadas não são acessíveis. É, necessário portanto, chamar a API da Yapoli passando a URL para que ela seja assinada. Uma vez assinada é possível então baixar os arquivos.

Importação de assets e automação

O carregamento de dados na Yapoli via automação a partir dos arquivos de entrada tem dois caminhos: via bucket na plataforma; ou via bucket direto no S3. No primeiro caso os parâmetros necessários podem estar no arquivo em definição no upload na própria plataforma. No segundo, é necessário fazer a importação direto via S3. Em ambos os casos, uma vez que o arquivo tem os parâmetros para automação ele segue o caminho de automação.

Automação pelo nome do arquivo

Para que a automação de um arquivo seja feita utilizando-se o nome dele é necessário configurar um webhook de automação com os parâmetros necessários para chamar uma API REST que retorne uma estrutura de dados já esperada. Deve-se, então, definir uma expressão regular que extraia as chaves de consulta à API do nome do arquivo para que a chamada seja bem sucedida e retorne os dados certos. Com o resultado da API, o processo pode então seguir para o ciclo de criação de itens.

Automação pelos campos Exif

Para que a automação possa seguir pelos campos exif é necessário definir quais os campos exif serão extraídos. Estes campos formaram uma estrutura de saída que será direcionada para o ciclo de criação de itens.

Automação por upload direto no S3

Caso busque-se fazer uma integração fazendo upload direto dos assets sem passar pela plataforma, o upload poderá ser feito diretamente num repositório S3 sob controle da Yapoli. Uma vez feito upload, o arquivo será processado e seguirá o fluxo de automação definido.

Criação de itens

Para que a criação de itens possa ser processada num ciclo de automação é necessário definir um mapeador (ainda sem documentação específica) feito em formato JSON que define os critérios para mapear os parâmetros de entrada (resultado dos passos anteriores de automação) com os dados da Yapoli. Com este mapeador definido o processo estará apto a então registrar o item e disponibilizar no DAM.

Tratamento de falhas

Em caso de falha no processo de automação os assets serão disponibilizados no bucket da plataforma, com indicação do motivo da falha, podendo ser reprocessados caso os fatores originários da falha estejam corrigido