Web Service OSR REST:
Guía de Consumo Web Service
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: ... 12
Llamada a los métodos: ... 14
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.https://api-scl01.masterosr.com/in/v2/
https://api-scl02.masterosr.com/in/v2/
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.
Web Service OSR REST R4:
Para realizar una carga, se debe utilizar el método POST.
El endpoint es el siguiente:
https://api-scl01.masterosr.com/in/v2/{IdCliente}/{IdContainer}
https://api-scl02.masterosr.com/in/v2/{IdCliente}/{IdContainer}
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.
El XML debe ser generado bajo la siguiente definición:
Headers
Header Tipo Requerido Descripción Ejemplo
Content-Type string Sí Formato del mensaje
Http
multipart/form-data
Content-Length int Sí Tamaño del mensaje
Http
> 1
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
2015-12-30T00: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.
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">https://api.masterosr.com/out/v1/1/2/demoApi/archivos/saludos_3.text</locatio n>
</OSRResponse>
Para la reemplazar archivos, se debe utilizar el método POST.
Los endpoint son los siguientes:
https://api-scl01.masterosr.com/in/v2/{IdCliente}/{IdContainer}
https://api-scl02.masterosr.com/in/v2/{IdCliente}/{IdContainer}
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 Http
multipart/form-data Content-
Length
int Sí Tamaño del mensaje Http
> 1 Autorization Basic Sí Credenciales para
acceder al servicio
X-OSR-
ClientPath
string Si Path único del archivo a reemplazar
/misarchivos/test.txt
X-OSR-
ReplaceVersion
string Si Indica que será reemplazo de archivo
true
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">https://api.masterosr.com/out/v1/1/2/demoApi/archivos/saludos_3.text</locatio n>
Body
name Tipo Descripción Ejemplo
File file Archivo a subir.
</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("10.1.1.1", 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"));
}
//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;
//tambien podriamos retornar solo la url del archivo.
//return response.Headers.Location.AbsoluteUri;
}// response }
}// content }// request
}// client
}// handler }
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("10.1.1.1", 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))
{
//agregamos el header X-OSR-ClientPath con el parametro client path.
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.
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;
//tambien podriamos retornar solo la url del archivo.
//return response.Headers.Location.AbsoluteUri;
}// response }
}// content }// request
}// client
}// handler }
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 = "https://api-scl01.masterosr.com/in/v2/";
var customer = "1";
var container = "2";
var username = "[email protected]";
var password = "xxxxx";
var validation = "<validation response=\"normal\"><set keyPractices=\"any\" allowHttp=\"true\"><httpAuth
validation=\"anonymous\"/></set></validation>";
var tags = "<tags/>";
var filePath = @"c:\temp\saludo.txt";
//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();
} } }
