Este documento fornece informações sobre o processo de moderação de conteúdo oferecido pela empresa Keepcon, incluindo detalhes sobre integração assíncrona e síncrona. Fornece exemplos de formatos XML para envio e recebimento de conteúdos e resultados, além de contatos para suporte.
2. Índice
Índice ....................................................................................................................... 0
1 Sobre este documento ........................................................................................... 1
2 Sobre o processo de moderação.............................................................................. 1
3 Método de integração assincrônico .......................................................................... 2
3.1 Enviando / obtendo conteúdos a serem moderados.............................................. 2
3.1.1 Formato de XML de envio ............................................................................ 3
3.1.2 Confirmação de recebimento ....................................................................... 4
3.2 Enviando resultados de moderação .................................................................... 5
3.2.1 Formato XML de resultado de moderação ...................................................... 5
Método de integração sincrônica ................................................................................... 7
4 Contato ............................................................................................................... 8
5 Apêndice .............................................................................................................. 9
5.1 Tabela descritiva de XML de input ...................................................................... 9
5.2 Tabela descritiva de XML de output .................................................................. 11
5.3 Tabela descritiva de XML de output de moderação sincrônica ............................. 12
3. 1 Sobre este documento
Este documento fornece informação necessária para utilizar os serviços de moderação
providos por Keepcon.
Está orientado às pessoas com conhecimentos técnicos, encarregadas do desenvolvimento
e/ou administração de um site web.
Ele está agrupado em seções, cobrindo o processo de moderação e documentação técnica
específica de como levar a cabo uma integração exitosa do processo de moderação em seu
site.
2 Sobre o processo de moderação
Keepcon oferece diferentes tipos de serviços de moderação, e está fora do alcance deste
documento detalhá-los, independente do serviço particular que se contrate, todos eles
incluem ao menos duas operações: enviar os conteúdos a serem moderados e receber
uma resposta para os conteúdos moderados.
Fica como tarefa do cliente incorporar ao seu processo interno o envio de dados para
moderação, a busca de resultados dos mesmos e a ação consequente em base a ditos
resultados, segundo suas próprias regras de negócio.
Versão 6.0
Outubro 2012 1
4. 3 Método de integração assincrônico
A integração assincrônica consiste em realizar as operações de envio de conteúdo a ser
moderado e a consulta de conteúdos moderados de maneira separada, sem correlação entre
elas. De tal forma , o cliente deverá programar dois processos independentes, um para cada
operação mencionada.
À continuação, descrevemos , em detalhes, cada uma das operações, com exemplos e
passos a seguir para uma integração exitosa.
3.1 Enviando / obtendo conteúdos a serem moderados
O cliente enviará a Keepcon os conteúdos a serem moderados de maneira periódica e em
lotes (definir a base do volume e necessidades concretas).
Por exemplo, se a média de volume de conteúdo a ser moderado gira em torno dos 1000
por hora, seria necessário enviar lotes de 50 elementos a cada 3 minutos.
Keepcon fornece um serviço web REST pelo qual o cliente enviará o conteúdo em formato
XML.
O endereço do serviço é o seguinte:
http://async.keepcon.com:63081/input/contentSet
Modo do uso do serviço:
1. Construir o XML com o conteúdo no formato que se detalha na seção 3.1.1.
2. Adquirir o serviço com um PUT HTTP enviando o XML no body do Request.
3. Ler a resposta do serviço adjunto no body do Response, e verificar se o envio se
realizou satisfatoriamente. Em caso contrario, tentar novamente o envio. Ver seção
3.1.2.
Versão 6.0
Outubro 2012 2
5. 3.1.1 Formato de XML de envio
O conteúdo enviado e a ser moderado deverá seguir o seguinte formato XML:
<?xml version="1.0" encoding="UTF-8" ?>
<import>
<contenttype>[account-name]</contenttype>
<contents>
<content id="1">
<author type="author">Pepe1989</author>
<url_context><![CDATA[http://blog.keepcon.com/?p=143]]></url_co
ntext>
<datetime>1262304000000</datetime>
<text><![CDATA[Olá amigo de toda comunidade!!!]]></text>
<img><![CDATA[http://misitio.com/una-foto.jpg]]></img>
<video><![CDATA[http://misitio.com/un-video.flv]]></video>
</content>
<content id="2">
<author type="author">Gandalf</author>
<url_context><![CDATA[http://blog.keepcon.com/?p=142]]></url_co
ntext>
<datetime>1262304000000</datetime>
<text><![CDATA[Olá, bem vindo!]]></text>
<img><![CDATA[http://misitio.com/una-foto.jpg]]></img>
<video><![CDATA[http://misitio.com/un-video.flv]]></video>
</content>
</contents>
</import>
Na seção, 5.1 detalha-se cada elemento do XML.
Versão 6.0
Outubro 2012 3
6. 3.1.2 Confirmação de recebimento
Como resposta ao envio, Keepcon enviará uma confirmação dizendo que foi recebido com
êxito um lote de conteúdos, junto com o identificador de lote referente ao tal envio. O
formato da resposta será o seguinte.
Formato da resposta:recepção positiva.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<setId>35</setId>
<status>OK</status>
</response>
Formato da resposta: recepção negativa.
<?xml version="1.0" encoding="UTF-8" ?>
<response>
<status>ERROR</status>
<errorMessage>Formato xml incorreto</errorMessage>
</response>
Por cada conjunto de conteúdos que Keepcon recebe, é fornecido um número de “lote” que
se indica pelo atributo setId. Este poderá ser utilizado pelo cliente para seguir um conjunto
de conteúdos dado: em que estado do processo de moderação se encontra, se já foi enviado
o resultado, etc.
Importante:
É obrigatório implementar um mecanismo de tentativas. Existe a possibilidade
que, por algum erro, imprevisto ou por tarefas de manutenção planificadas, e
oportunamente comunicadas, o serviço de recebimento de conteúdos esteja fora
do ar. Nesses casos o processo de invocação deverá detectar o código de erro ou
a falta de resposta, e deverá proceder outras tentativas, com certa frequencia,até
poder injetar os conteúdos na plataforma de Keepcon.
Versão 6.0
Outubro 2012 4
7. 3.2 Enviando resultados de moderação
Uma vez processados os conteúdos, os resultados estarão disponíveis para o cliente.
O cliente consultará periodicamente o serviço web para obter os resultados dos conteúdos
moderados.
Para isto, Keepcon fornece um serviço de web REST onde é possível verificar os resultados.
O endereço é o seguinte:
http://async.keepcon.com:63081/output/contentSet?contextName=[account-name]
onde [account-name] é o nome da conta de sua empresa.
Modo de uso do serviço:
1. Requisitar o serviço com um PUT HTTP, enviando como parâmetro o nome da conta
oportunamente provida por Keepcon.
2. Ler a resposta do serviço adjunta no body do Response. O formato de resposta
detalhamos na seguinte seção. No caso de não haver resposta, significa que não há
resultados de moderação pendentes a serem consultados.
3. Aplicar os resultados de moderação segundo suas próprias regras de negócio.
3.2.1 Formato XML de resultado de moderação
Os resultados da moderação que se enviam ao cliente terão o seguinte formato XML:
<?xml version="1.0" encoding="UTF-8"?>
<export setId="3674">
<contents>
<content id="1" >
<moderatorName>moderador1</moderatorName>
<moderationDate>1272973151662</moderationDate>
<moderationDecision>REJECTED</moderationDecision>
<tagging>
<tag>Inapropriado</tag>
</tagging>
</content>
<content id="2" >
Versão 6.0
Outubro 2012 5
8. <moderatorName>moderador1</moderatorName>
<moderationDate>1272973151662</moderationDate>
<moderationDecision>APPROVED</moderationDecision>
<tagging/>
</content>
</contents>
</export>
Na seção, 5.2 detalhamoscada elemento do XML.
Versão 6.0
Outubro 2012 6
9. Método de integração sincrônica
Neste cenário, o cliente enviará a Keepcon os conteúdos a serem moderados um a um,
obtendo o resultado de moderação de maneira sincrônica para cada envio.
Para isto, Keepcon fornece um serviço web REST por onde enviar a informação.
O endereço é o seguinte:
http://sync.keepcon.com:63081/synchronic/moderate/
Modo de uso do serviço:
1. Construir o XML com o conteúdo no formato que se detalha a continuação.
2. Adquirir o serviço com um PUT HTTP, enviando o XML no body do Request.
3. Ler a resposta do serviço, anexar no body do Response e verificar se a operação foi
realizada satisfatoriamente. Ver formato de XML de resposta que se detalha à
continuação.
4. Aplicar os resultados de moderação segundo suas próprias regras de negócio.
O conteúdo enviado a ser moderado deverá seguir o seguinte formato XML:
<?xml version="1.0" encoding="UTF-8" ?>
<import>
<contenttype>[account-name]</contenttype>
<contents>
<content id="1">
<author type="author">Pepe1989</author>
<url_context><![CDATA[http://blog.keepcon.com/?p=143]]></url_co
ntext>
<datetime>1262304000000</datetime>
<text><![CDATA[Olá amigos de toda a comunidade!!!]]></text>
</content>
</contents>
</root>
Nota: no caso de que o serviço receba mais de um conteúdo a ser moderado em um mesmo
envio, será cancelada a moderação e haverá uma resposta com status de ERRO.
Versão 6.0
Outubro 2012 7
10. Como resposta, o serviço devolverá os resultados da moderação no seguinte formato XML:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<status>OK</status>
<content id="1" >
<moderationDecision>REJECTED</moderationDecision>
<tagging>
<tag>nú</tag>
<tag>contato</tag>
</tagging>
</content>
</response>
Na seção 5.3 detalhamos cada elemento do XML.
Importante:
É obrigatório implementar um mecanismo de tentativas. Existe a possibilidade
que por algum erro, imprevisto ou por tarefas de manutenção planificadas, e
oportunamente comunicadas, o serviço de recebimento de conteúdos esteja fora
do ar. Nesses casos, o processo de invocação deverá detectar o código de erro ou
a falta de resposta, e deverão proceder outras tentativas, com certa frequencia,
até poder injetar os conteúdos na plataforma de Keepcon.
4 Contato
Ante qualquer dúvida ou consulta, pode contatar-se com um profissional de Keepcon, que
poderá auxiliá-lo no processo de integração, nos seguintes formatos:
• Correio eletrônico: support@keepcon.com
Versão 6.0
Outubro 2012 8
11. 5 Apêndice
5.1 Tabela descritiva de XML de input
Na tabela abaixo, descrevemos cada um dos elementos deste XML.
Elemento / Tipo de dado Descrição Obrigatório
atributo
setId Elemento. Cadeia de Identificador de lote de Não.
caracteres. importação, gerado pelo cliente.
contenttype Elemento. Cadeia. Este elemento tem a descrição Sim.
da conta através da qual se
identifica o tipo de conteúdo do
cliente.
Este valor é imutável e será
provido por Keepcon.
contents Elemento. Este elemento contém múltiplos Sim.
elementos filhos do tipo content,
com os conteúdos a serem
moderados.
content Elemento. Conteúdo a ser moderado. Sim.
id Título. Inteiro Identificador único de conteúdo Sim.
extenso positivo. provido pelo cliente.
author Elemento. Cadeia. Nome do autor do conteúdo. Não, mas
Este dado não é obrigatório se o sugerido.
cliente não está interessado em
realizar seguimento por usuário.
Sugere-se fornecê-lo, de todos
os modos, dado que o processo
de moderação é mais eficiente
tendo este dado presente.
Versão 6.0
Outubro 2012 9
12. url_context Atributo. Cadeia. URL onde se encontra o Não, mas
conteúdo. O propósito é poder sugerido.
visualizar o conteúdo em seu
contexto para desambiguar no
caso de dúvida.
datetime Atributo. Formato Data e hora de criação do Não,
UTC. conteúdo para poder empregar a massugerido.
ordem cronológico na
priorização da fila de
moderação, segundo seja o
modelo: pré-moderação ou pós-
moderação.
type Atributo. Cadeia. Interno da plataforma. Tipo de Sim.
dado do campo.
text Elemento. Cadeia. Conteúdo a ser moderado. Sim.
Nota: sempre encerrar o
conteúdo entre <![CDATA[]]>,
para evitar que caracteres
estranhos impeçam o correto
uso do conteúdo.
img Elemento. Cadeia. URL apontando a imagem que se Não.
deseja moderar.
Os formatos suportados são:
GIF, JPG, PNG y BMP.
video Elemento. Cadeia. URL apontando ao vídeo que se Não.
deseja moderar.
Nota: Keepcon suporta
praticamente qualquer formato
padrão de vídeo, mas
internamente para processá-lo o
converte a FLV assim, se o
envio é feito, originalmente,
como FLV, melhora-se, de
forma notória, a eficiência do
processo de moderação,
impactando positivamente nos
tempos de resposta.
Versão 6.0
Outubro 2012 10
13. 5.2 Tabela descritiva de XML de output
Na tabela abaixo, descrevemos cada um dos elementos deste XML.
Elemento / Tipo de dado Descrição
atributo
setId Atributo. Inteiro Para poder realizar um
Longo positivo. seguimento apropriado do envio
dos resultados de moderação,
Keepcon gera um identificador
único para cada conjunto de
resultados enviados.
contents Elemento. Este elemento contém múltiplos
elementos filhos de tipo content.
content Elemento. Um conteúdo particular.
id Atributo. Inteiro Identificador único de conteúdo
longo positivo. gerado pelo cliente.
Moderação Decisão Atributo. Cadeia. Mostra a decisão de moderação
do conteúdo. Os possíveis
valores são:
• REJECTED
• APPROVED
• UNKNOWN
tagging Elemento Lista de motivos de recusa,
resultante do processo de
moderação do conteúdo. Em caso
de que o conteúdo tenha um
status de aprovado, a lista de
motivos de recusas estará vazia.
Versão 6.0
Outubro 2012 11
14. tag Atributo. Cadeia. Categorização do conteúdo
resultante do processo de
moderação. Os valores serão
definidos por cada cliente,
segundo suas regras de
moderação.
5.3 Tabela descritiva de XML de output de moderação sincrônica
Na tabela abaixo, descrevemos cada um dos elementos deste XML.
Elemento / Tipo de dato Descrição
atributo
status Atributo. Cadeia. Indica se a solicitação pode ser
atendida ou não. Os possíveis
valores são:
• OK
• ERROR
content Elemento. Um conteúdo particular.
id Atributo. Inteiro Identificador único de conteúdo
longo positivo. gerado pelo cliente.
Moderação Decisão Atributo. Cadeia. Mostra a decisão de moderação
do conteúdo. Os possíveis
valores são:
• REJECTED
• APPROVED
• UNKNOWN
tagging Elemento Lista de motivos de recusa,
resultante do processo de
moderação do conteúdo. No caso
doconteúdo ter um status de
aprovado, a lista de motivos de
recusas estará vazia.
Versão 6.0
Outubro 2012 12
15. tag Atributo. Cadeia. Categorização do conteúdo,
resultante do processo de
moderação. Os valores serão
definidos por cada cliente
segundo suas regras de
moderação.
Versão 6.0
Outubro 2012 13