Web Service OSR REST: Guía de Consumo Web Service

Transcripción

1 Web Service OSR REST: Guía de Consumo Web Service

2 Indice Indice... 2 Guía de consumo... 3 Método POST... 3 Código de resultado: Response... 3 Paylod:... 3 El endpoint es el siguiente:... 4 El XML debe ser generado bajo la siguiente definición:... 5 Headers... 5 Body... 5 Ejemplo:... 6 El Resultado:... 6 Los endpoint son los siguientes:... 7 Headers... 7 Body... 8 Ejemplo:... 8 El Resultado... 8 A continuación, un ejemplo para integrar estos métodos... 9 Carga de archivos:... 9 Reemplazo de archivos: Llamada a los métodos:... 14

3 Guía de consumo El presente documento está orientado facilitar las operaciones relacionadas con realizar carga o reemplazo de archivos en la nube de MasterBase. Definimos como: Endpoint: Dirección completa que incluye una URL base más los parámetros necesarios (obligatorios u opcionales) para su ejecución. URL Base: Es la dirección raíz para el consumo de los Web Services. Un Web Service posee sólo un método: Método POST: Utilizado para la carga o reemplazo de archivos. Cada ejecución de un Web Service, entrega: Código de resultado: Response El RESPONSE es un código que representa el resultado de la ejecución: o 201 : resultado satisfactorio o 400 : problema en la ejecución o 500 : problema en el servicio (interno) o Etc. Paylod: Consiste en la información que se adjunta al llamado Web Service, como información necesaria para la acción que estamos realizando.

4 Web Service OSR REST R4: Para realizar una carga, se debe utilizar el método POST. El endpoint es el siguiente: Donde: IdCliente Identificador numérico de la cuenta del cliente Parámetro Obligatorio IdContainer Identificador del contenedor sobre el cual se realizará la carga Parámetro Obligatorio Utilizar credenciales válidas para el consumo de Web Service, para este servicio. Para este método es necesario incluir una estructura XML en el PAYLOAD y debe ser del tipo multipart/form-data. Esta carga solamente acepta la publicación de un archivo a la vez. Si se quiere publicar un número mayor de archivos se debe repetir el proceso anteriormente descrito tantas veces como sea necesario. Se aconseja utilizar herramientas para consumo de web service que permitan la carga de archivos, por ejemplo, Postman.

5 El XML debe ser generado bajo la siguiente definición: Headers Header Tipo Requerido Descripción Ejemplo Content-Type string Sí Formato del mensaje multipart/form-data Http Content-Length int Sí Tamaño del mensaje > 1 Http Autorization Basic Sí Credenciales para acceder al servicio X-OSR-ClientPath string Opcional Path único del archivo /misarchivos/test.txt En el caso de no indicar valor para este parámetro, el sistema generara un identificador único. X-OSR-ExpirationDate datetime Opcional Fecha de expiración del archivo T00:00:00 Body Name Tipo Descripción Ejemplo validation String(XML) XML validation, contiene parámetros de restricción de acceso al archivo.(acá agregar referencia a la estructura y parámetros de este XML ) <validation response="normal"> <set keypractices="any" allowhttp="true"> <httpauth validation="anonymous"/> </set> </validation> tags String(XML) XML Tags, contiene etiquetas para poder hacer búsquedas de archivos. <tags> <categoria>viajes</categoria> <campaña>promoción USA</campaña> </tags> File file Archivo a subir.

6 Ejemplo: El Resultado: El extracto del resultado de la lista (en caso de éxito), reflejará la siguiente estructura: <OSRResponse> <statuscode>201</statuscode> <statusdescription>created</statusdescription> <location Hash="e976af72d9a6644d7422c16d64ce597a" FileSize="33"> n> </OSRResponse>

7 Para la reemplazar archivos, se debe utilizar el método POST. Los endpoint son los siguientes: Donde: IdCliente Identificador numérico de la cuenta del cliente Parámetro Obligatorio IdContainer Identificador del contenedor sobre el cual se realizará la carga Parámetro Obligatorio Utilizar credenciales válidas para el consumo de Web Service, para este servicio. Para este método es necesario incluir una estructura XML en el PAYLOAD y debe ser del tipo multipart/form-data. Esta carga solamente acepta la publicación de un archivo a la vez. Si se quiere publicar un número mayor de archivos se debe repetir el proceso anteriormente descrito tantas veces como sea necesario. Se aconseja utilizar herramientas para consumo de web service que permitan la carga de archivos, por ejemplo, Postman. Headers Header Tipo Requerido Descripción Ejemplo Content-Type string Sí Formato del mensaje multipart/form-data Http Content- int Sí Tamaño del mensaje > 1 Length Http Autorization Basic Sí Credenciales para acceder al servicio X-OSR- ClientPath X-OSR- ReplaceVersion string Si Path único del archivo a reemplazar string Si Indica que será reemplazo de archivo /misarchivos/test.txt true

8 Body name Tipo Descripción Ejemplo File file Archivo a subir. Ejemplo: El Resultado El resultado (en caso de éxito), reflejará la siguiente estructura: <OSRResponse> <statuscode>200</statuscode> <statusdescription>created</statusdescription> <location Hash="e976af72d9a6644d7422c16d64ce597a" FileSize="33"> n>

9 </OSRResponse> A continuación, un ejemplo para integrar estos métodos Carga de archivos: public static string Upload(string urlbase, string customer, string container, string username, string password, string validation, string tags, string filepath, string clientpath, DateTime? expdate, double? timeout) #region Validaciones de parámetros. // Intencional mente se omiten las validaciones de los parametros, con el fin de simplicar. #endregion //creamos el objeto HttpClientHandler, para setear credenciales y otros parametros. using (var handler = new HttpClientHandler()) //se fuerza a enviar las credenciales. handler.preauthenticate = true; //se agregan las credenciales proporcionadas. handler.credentials = new NetworkCredential(username, password); //acá se puede definir un proxy en el caso que sea necesario //handler.proxy = new WebProxy(" ", 8080); var baseapiuri = new Uri(urlBase); var customerapiuri = new Uri(baseApiUri, string.format("0/1", customer, container)); //creamos el objeto HttpClient que se encargara de enviar el request. using (var client = new HttpClient(handler)) //si el parametro timeout tiene valor. if (timeout.hasvalue) client.timeout = TimeSpan.FromSeconds(timeout.Value); else //valor por defecto. client.timeout = TimeSpan.FromSeconds(30); //creamos el objeto request que contentrá el mensaje(headers y contenido) using (var request = new HttpRequestMessage(HttpMethod.Post, customerapiuri)) //si el parametro fecha de expiración tiene valor, se agrega el header X-OSR-ExpirationDate. if (expdate.hasvalue) request.headers.add("x-osr-expirationdate", expdate.value.tostring("s"));

10 //si el paramtro client path tiene valor se agrega el header X-OSR-ClientPath. if (!string.isnullorwhitespace(clientpath)) request.headers.add("x-osr-clientpath", clientpath); using (var content = new MultipartFormDataContent()) //agregamos dentro del objeto conetido el XML validation. var validationcontent = new StringContent(validation); validationcontent.headers.contenttype = null; content.add(validationcontent, "\"validation\""); //agregamos dentro del objeto conetido el XML validation. var tagscontent = new StringContent(tags); tagscontent.headers.contenttype = null; content.add(tagscontent, "\"tags\""); //creamos el objecto StreamContent para agregar el archivo al mensaje. using (var filecontent = new StreamContent(new FileStream(filePath, FileMode.Open, FileAccess.Read))) //definimos el disposition del archivo. filecontent.headers.contentdisposition = new ContentDispositionHeaderValue("form-data") Name = "\"file\"", FileName = "\"" + Path.GetFileName(filePath) + "\"" ; //indicamos el contenttype del archivo. filecontent.headers.contenttype = new MediaTypeHeaderValue(MimeTypes.GetMimeType(filePath)); //agregamos el archivo al contenido del mensaje. content.add(filecontent, "file"); //asignamos el contenido al request. request.content = content; //hacemos el request y obtenemos el response. using (var response = client.sendasync(request).result) //nos aseguramos que se genere un exception si la respuesta no es satisfactoria. response.ensuresuccessstatuscode(); //leemos el contenido de la respuesta var responsestring = response.content.readasstringasync().result; //retornamos la respuesta. return responsestring;

11 archivo. //tambien podriamos retornar solo la url del //return response.headers.location.absoluteuri; // response // content // request // client // handler

12 Reemplazo de archivos: public static string Replace(string urlbase, string customer, string container, string username, string password, string filepath, string clientpath, int? timeout) //creamos el objeto HttpClientHandler, para setiar credenciales y otros parametros. using (var handler = new HttpClientHandler()) //se fuerza a enviar las credenciales. handler.preauthenticate = true; //se agregan las credenciales. handler.credentials = new NetworkCredential(username, password); //acá se puede definir un proxy en el caso que sea necesario //handler.proxy = new WebProxy(" ", 8080); var baseapiuri = new Uri(urlBase); var customerapiuri = new Uri(baseApiUri, string.format("0/1", customer, container)); //creamos el objeto HttpClient que se encargara de enviar el request. using (var client = new HttpClient(handler)) //si el parametro timeout tiene valor. if (timeout.hasvalue) client.timeout = TimeSpan.FromSeconds(timeout.Value); else //valor por defecto. client.timeout = TimeSpan.FromSeconds(30); //creamos el objeto request que contentrá el mensaje(headers y contenido) using (var request = new HttpRequestMessage(HttpMethod.Post, customerapiuri)) client path. //agregamos el header X-OSR-ClientPath con el parametro request.headers.add("x-osr-clientpath", clientpath); //agregamos el header X-OSR-ReplaceVersion para indicar al servicio que es un reemplazo. request.headers.add("x-osr-replaceversion", "true"); using (var content = new MultipartFormDataContent()) //creamos el objecto StreamContent para agregar el archivo al mensaje. using (var filecontent = new StreamContent(new FileStream(filePath, FileMode.Open, FileAccess.Read))) //definimos el disposition del archivo.

13 filecontent.headers.contentdisposition = new ContentDispositionHeaderValue("form-data") Name = "\"file\"", FileName = "\"" + Path.GetFileName(filePath) + "\"" ; //indicamos el contenttype del archivo. filecontent.headers.contenttype = new MediaTypeHeaderValue(MimeTypes.GetMimeType(filePath)); //agregamos el archivo al contenido del mensaje. content.add(filecontent, "file"); //asignamos el contenido al request. request.content = content; //hacemos el request y obtenemos el response. using (var response = client.sendasync(request).result) //nos aseguramos que se genere un exception si la respuesta no es satisfactoria. response.ensuresuccessstatuscode(); //leemos el contenido del la respueta var responsestring = response.content.readasstringasync().result; //retornamos la respuesta. return responsestring; archivo. //tambien podriamos retornar solo la url del //return response.headers.location.absoluteuri; // response // content // request // client // handler

14 Llamada a los métodos: class Program static void Main(string[] args) try //Importante: En este ejemplo se omiten varias validaciones y y control de excepciones con el fin de hacer mas simple y entendible el codigo. //Parametros de entrada de ejemplos var urlbase = " var customer = "1"; var container = "2"; var username = "user@domain.com"; var password = "xxxxx"; var validation = "<validation response=\"normal\"><set keypractices=\"any\" allowhttp=\"true\"><httpauth validation=\"anonymous\"/></set></validation>"; var tags = "<tags/>"; var filepath //Para mas detalles ir a la clase OSR, para ver la definicion de Upload. var resultupload = OSR.Upload(urlBase, customer, container, username, password, validation, tags, filepath); Console.WriteLine(resultUpload); //Para mas detalles ir a la clase OSR, para ver la definicion de Replace. var resultreplace = OSR.Replace(urlBase, customer, container, username, password, filepath, "misdocumentos/demo/saludo.txt"); Console.WriteLine(resultReplace); Console.ReadKey(); catch (Exception ex) Console.WriteLine(ex); Console.ReadKey();