Keepcon integrations- pt-

377 visualizações

Publicada em

0 comentários
0 gostaram
Estatísticas
Notas
  • Seja o primeiro a comentar

  • Seja a primeira pessoa a gostar disto

Sem downloads
Visualizações
Visualizações totais
377
No SlideShare
0
A partir de incorporações
0
Número de incorporações
99
Ações
Compartilhamentos
0
Downloads
1
Comentários
0
Gostaram
0
Incorporações 0
Nenhuma incorporação

Nenhuma nota no slide

Keepcon integrations- pt-

  1. 1. Guia de ImplementaçãoVersão 6.0Outubro 2012 1
  2. 2. ÍndiceÍndice ....................................................................................................................... 01 Sobre este documento ........................................................................................... 12 Sobre o processo de moderação.............................................................................. 13 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 ...................................................... 5Método de integração sincrônica ................................................................................... 74 Contato ............................................................................................................... 85 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. 3. 1 Sobre este documentoEste documento fornece informação necessária para utilizar os serviços de moderaçãoprovidos por Keepcon.Está orientado às pessoas com conhecimentos técnicos, encarregadas do desenvolvimentoe/ou administração de um site web.Ele está agrupado em seções, cobrindo o processo de moderação e documentação técnicaespecífica de como levar a cabo uma integração exitosa do processo de moderação em seusite.2 Sobre o processo de moderaçãoKeepcon oferece diferentes tipos de serviços de moderação, e está fora do alcance destedocumento detalhá-los, independente do serviço particular que se contrate, todos elesincluem ao menos duas operações: enviar os conteúdos a serem moderados e receberuma resposta para os conteúdos moderados.Fica como tarefa do cliente incorporar ao seu processo interno o envio de dados paramoderação, a busca de resultados dos mesmos e a ação consequente em base a ditosresultados, segundo suas próprias regras de negócio.Versão 6.0Outubro 2012 1
  4. 4. 3 Método de integração assincrônicoA integração assincrônica consiste em realizar as operações de envio de conteúdo a sermoderado e a consulta de conteúdos moderados de maneira separada, sem correlação entreelas. De tal forma , o cliente deverá programar dois processos independentes, um para cadaoperação mencionada.À continuação, descrevemos , em detalhes, cada uma das operações, com exemplos epassos a seguir para uma integração exitosa.3.1 Enviando / obtendo conteúdos a serem moderadosO cliente enviará a Keepcon os conteúdos a serem moderados de maneira periódica e emlotes (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 1000por 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 formatoXML.O endereço do serviço é o seguinte:http://async.keepcon.com:63081/input/contentSetModo 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.0Outubro 2012 2
  5. 5. 3.1.1 Formato de XML de envioO 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.0Outubro 2012 3
  6. 6. 3.1.2 Confirmação de recebimentoComo 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. Oformato 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” quese indica pelo atributo setId. Este poderá ser utilizado pelo cliente para seguir um conjuntode conteúdos dado: em que estado do processo de moderação se encontra, se já foi enviadoo resultado, etc.Importante:É obrigatório implementar um mecanismo de tentativas. Existe a possibilidadeque, por algum erro, imprevisto ou por tarefas de manutenção planificadas, eoportunamente comunicadas, o serviço de recebimento de conteúdos esteja forado ar. Nesses casos o processo de invocação deverá detectar o código de erro oua falta de resposta, e deverá proceder outras tentativas, com certa frequencia,atépoder injetar os conteúdos na plataforma de Keepcon.Versão 6.0Outubro 2012 4
  7. 7. 3.2 Enviando resultados de moderaçãoUma 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údosmoderados.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çãoOs 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.0Outubro 2012 5
  8. 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.0Outubro 2012 6
  9. 9. Método de integração sincrônicaNeste 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 mesmoenvio, será cancelada a moderação e haverá uma resposta com status de ERRO.Versão 6.0Outubro 2012 7
  10. 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 possibilidadeque por algum erro, imprevisto ou por tarefas de manutenção planificadas, eoportunamente comunicadas, o serviço de recebimento de conteúdos esteja forado ar. Nesses casos, o processo de invocação deverá detectar o código de erro oua falta de resposta, e deverão proceder outras tentativas, com certa frequencia,até poder injetar os conteúdos na plataforma de Keepcon.4 ContatoAnte qualquer dúvida ou consulta, pode contatar-se com um profissional de Keepcon, quepoderá auxiliá-lo no processo de integração, nos seguintes formatos: • Correio eletrônico: support@keepcon.comVersão 6.0Outubro 2012 8
  11. 11. 5 Apêndice5.1 Tabela descritiva de XML de inputNa 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.0Outubro 2012 9
  12. 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.0Outubro 2012 10
  13. 13. 5.2 Tabela descritiva de XML de outputNa 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.0Outubro 2012 11
  14. 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ônicaNa 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.0Outubro 2012 12
  15. 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.0Outubro 2012 13

×