diff --git a/man/consume.Rd b/man/consume.Rd index f8ed995..f99d6c4 100644 --- a/man/consume.Rd +++ b/man/consume.Rd @@ -9,15 +9,13 @@ consume(endpoint, ..., globalParam, retryDelay = 10, output = "output1") \arguments{ \item{endpoint}{AzureML Web Service endpoint returned by \code{\link{endpoints}}} -\item{...}{variable number of requests entered as lists in key-value format; -optionally a single data frame argument.} +\item{...}{variable number of requests entered as lists in key-value format; optionally a single data frame argument.} \item{globalParam}{global parameters entered as a list, default value is an empty list} \item{retryDelay}{the time in seconds to delay before retrying in case of a server error} -\item{output}{name of the output port to return usually 'output1' or 'output2'; -set to NULL to return everything as raw results in JSON-encoded list form} +\item{output}{name of the output port to return usually 'output1' or 'output2'; set to NULL to return everything as raw results in JSON-encoded list form} } \value{ data frame containing results returned from web service call @@ -27,67 +25,87 @@ Score data represented as lists where each list key represents a parameter of the web service. } \note{ -Set \code{...} to a list of key/value pairs corresponding to web service -inputs. Optionally, set \code{...} to a single data frame with columns corresponding -to web service variables. The data frame approach returns output from the evaluation -of each row of the data frame (see the examples). +Set \code{...} to a list of key/value pairs corresponding to web service inputs. Optionally, set \code{...} to a single data frame with columns corresponding to web service variables. The data frame approach returns output from the evaluation of each row of the data frame (see the examples). } \examples{ \dontrun{ -# Use a default configuration in ~/.azureml, alternatively -# see help for `workspace`. -ws <- workspace() - -# Really simple example: -add <- function(x,y) x + y -endpoint <- publishWebService(ws, add, "addme", list(x="numeric", y="numeric"), list(ans="numeric")) -consume(endpoint, list(x=pi, y=2)) - - -# A neat trick to evaluate any expression in the Azure ML virtual -# machine R session and view its output: -ep <- publishWebService(ws, fun=function(expr) { - paste(capture.output(eval(parse(text=expr))), collapse="\\n")}, - name="commander", inputSchema=list(x="character"), - outputSchema=list(ans="character")) -cat(consume(ep, list=(expr="getwd()"))$ans) -cat(consume(ep, list=(expr=".packages(all=TRUE)"))$ans) - - -# The following example illustrates scoping rules. Note that the function -# refers to the variable y defined outside the function body. That value -# will be exported with the service. -y <- pi -ep <- publishWebService(ws, fun=function(x) x + y, name="lexi", - inputSchema=list(x="numeric"), outputSchema=list(ans="numeric")) -cat(consume(ep, list(x=2))$ans) - - -# Example showing the use of consume to score all the rows of a data frame -# at once. The columns of the data frame correspond to the input parameters -# of the web service. -f <- function(a,b,c,d) list(sum=a+b+c+d, prod=a*b*c*d) -ep <- publishWebService(ws, f, name="rowSums", - inputSchema=list(a="numeric", b="numeric", c="numeric", d="numeric"), - outputSchema=list(sum="numeric", prod="numeric")) -x <- head(iris[,1:4]) # First four columns of iris - -# Note the following will FAIL because of a name mismatch in the arguments -# (with an informative error): -consume(ep, x, retryDelay=1) -# We need the columns of the data frame to match the inputSchema: -names(x) <- letters[1:4] -# Now we can evaluate all the rows of the data frame in one call: -consume(ep, x) -# output should look like: -# sum prod -# 1 10.2 4.998 -# 2 9.5 4.116 -# 3 9.4 3.9104 -# 4 9.4 4.278 -# 5 10.2 5.04 -# 6 11.4 14.3208 - + # Use a default configuration in ~/.azureml, alternatively + # see help for `workspace`. + ws <- workspace() + + # Really simple example: + add <- function(x,y) x + y + endpoint <- publishWebService(ws, + fun = add, + name = "addme", + inputSchema = list(x="numeric", + y="numeric"), + outputSchema = list(ans="numeric")) + consume(endpoint, list(x=pi, y=2)) + + + # A neat trick to evaluate any expression in the Azure ML virtual + # machine R session and view its output: + ep <- publishWebService(ws, + fun = function(expr) { + paste(capture.output( + eval(parse(text=expr))), collapse="\\n") + }, + name="commander", + inputSchema = list(x = "character"), + outputSchema = list(ans = "character")) + cat(consume(ep, list(x = "getwd()"))$ans) + cat(consume(ep, list(x = ".packages(all=TRUE)"))$ans) + cat(consume(ep, list(x = "R.Version()"))$ans) + + + # The following example illustrates scoping rules. Note that the function + # refers to the variable y defined outside the function body. That value + # will be exported with the service. + y <- pi + ep <- publishWebService(ws, + fun = function(x) x + y, + name = "lexi", + inputSchema = list(x = "numeric"), + outputSchema = list(ans = "numeric")) + cat(consume(ep, list(x=2))$ans) + + + # Example showing the use of consume to score all the rows of a data frame + # at once. The columns of the data frame correspond to the input parameters + # of the web service. + f <- function(a,b,c,d) list(sum = a+b+c+d, prod = a*b*c*d) + ep <- publishWebService(ws, + f, + name = "rowSums", + inputSchema = list( + a="numeric", + b="numeric", + c="numeric", + d="numeric" + ), + outputSchema = list( + sum ="numeric", + prod = "numeric") + ) + x <- head(iris[,1:4]) # First four columns of iris + + # Note the following will FAIL because of a name mismatch in the arguments + # (with an informative error): + consume(ep, x, retryDelay=1) + # We need the columns of the data frame to match the inputSchema: + names(x) <- letters[1:4] + # Now we can evaluate all the rows of the data frame in one call: + consume(ep, x) + # output should look like: + # sum prod + # 1 10.2 4.998 + # 2 9.5 4.116 + # 3 9.4 3.9104 + # 4 9.4 4.278 + # 5 10.2 5.04 + # 6 11.4 14.3208 + } } \seealso{ diff --git a/man/endpoints.Rd b/man/endpoints.Rd index c934b18..d9c9d49 100644 --- a/man/endpoints.Rd +++ b/man/endpoints.Rd @@ -16,8 +16,7 @@ getEndpoints(ws, service_id, endpoint_id, \item{service_id}{A web service Id, for example returned by \code{\link{services}}.} -\item{endpoint_id}{An optional endpoint id. If supplied, return the endpoint information for just -that id. Leave undefined to return a data.frame of all end points associated with the service.} +\item{endpoint_id}{An optional endpoint id. If supplied, return the endpoint information for just that id. Leave undefined to return a data.frame of all end points associated with the service.} \item{uri}{The AzureML web services URI} } diff --git a/man/publishWebService.Rd b/man/publishWebService.Rd index e3b18f0..6396090 100644 --- a/man/publishWebService.Rd +++ b/man/publishWebService.Rd @@ -43,8 +43,7 @@ in the web service} \code{\link{workspace}}.} } \value{ -A data.frame describing the new service endpoints, cf. \code{\link{endpoints}}. The output - can be directly used by the \code{\link{consume}} function. +A data.frame describing the new service endpoints, cf. \code{\link{endpoints}}. The output can be directly used by the \code{\link{consume}} function. } \description{ Publish a function to Microsoft Azure Machine Learning as a web service. The @@ -54,79 +53,93 @@ The function to be published is limited to inputs/outputs consisting of lists of scalar values. } \note{ -AzureML data types are different than, but related to, R types. You may specify - the R types \code{numeric, logical, integer,} and \code{character} and those will - be specified as AzureML types \code{double, boolean, int32, string}, respectively. - -Leave the \code{wsid} parameter undefined to create a new AzureML web service, or -specify the ID of an existing web service to update it, replacing the function -and required R pacakges with new values. Although the API allows that the name, -input and output schema to also be specified when updating it's not possible to -change those values. -The \code{\link{updateWebService}} function is nearly an alias for \code{\link{publishWebService}}, -differing only in that the \code{wsid} parameter is required by \code{\link{updateWebService}}. - -The \code{publishWebService} function automatically exports objects required by the function -to a working environment in the AzureML machine, including objects accessed within the function -using lexical scoping rules. Use the \code{exports} parameter to explicitly include other objects that -are needed. Use \code{noexport} to explicitlt prevent objects from being exported. +AzureML data types are different than, but related to, R types. You may specify the R types \code{numeric, logical, integer,} and \code{character} and those will be specified as AzureML types \code{double, boolean, int32, string}, respectively. + +Leave the \code{wsid} parameter undefined to create a new AzureML web service, or specify the ID of an existing web service to update it, replacing the function and required R pacakges with new values. Although the API allows that the name, input and output schema to also be specified when updating it's not possible to change those values. + +The \code{\link{updateWebService}} function is nearly an alias for \code{\link{publishWebService}}, differing only in that the \code{wsid} parameter is required by \code{\link{updateWebService}}. + +The \code{publishWebService} function automatically exports objects required by the function to a working environment in the AzureML machine, including objects accessed within the function using lexical scoping rules. Use the \code{exports} parameter to explicitly include other objects that are needed. Use \code{noexport} to explicitlt prevent objects from being exported. } \examples{ \dontrun{ -# Use a default configuration in ~/.azureml, alternatively -# see help for `workspace`. -ws <- workspace() - -# Really simple example: -add <- function(x,y) x + y -endpoint <- publishWebService(ws, add, "addme", list(x="numeric", y="numeric"), list(ans="numeric")) -consume(endpoint, list(x=pi, y=2)) - - -# A neat trick to evaluate any expression in the Azure ML virtual -# machine R session and view its output: -ep <- publishWebService(ws, fun=function(expr) { - paste(capture.output(eval(parse(text=expr))), collapse="\\n")}, - name="commander", inputSchema=list(x="character"), - outputSchema=list(ans="character")) -cat(consume(ep, list=(expr="getwd()"))$ans) -cat(consume(ep, list=(expr=".packages(all=TRUE)"))$ans) - - -# The following example illustrates scoping rules. Note that the function -# refers to the variable y defined outside the function body. That value -# will be exported with the service. -y <- pi -ep <- publishWebService(ws, fun=function(x) x + y, name="lexi", - inputSchema=list(x="numeric"), outputSchema=list(ans="numeric")) -cat(consume(ep, list(x=2))$ans) - - -# Example showing the use of consume to score all the rows of a data frame -# at once. The columns of the data frame correspond to the input parameters -# of the web service. -f <- function(a,b,c,d) list(sum=a+b+c+d, prod=a*b*c*d) -ep <- publishWebService(ws, f, name="rowSums", - inputSchema=list(a="numeric", b="numeric", c="numeric", d="numeric"), - outputSchema=list(sum="numeric", prod="numeric")) -x <- head(iris[,1:4]) # First four columns of iris - -# Note the following will FAIL because of a name mismatch in the arguments -# (with an informative error): -consume(ep, x, retryDelay=1) -# We need the columns of the data frame to match the inputSchema: -names(x) <- letters[1:4] -# Now we can evaluate all the rows of the data frame in one call: -consume(ep, x) -# output should look like: -# sum prod -# 1 10.2 4.998 -# 2 9.5 4.116 -# 3 9.4 3.9104 -# 4 9.4 4.278 -# 5 10.2 5.04 -# 6 11.4 14.3208 - + # Use a default configuration in ~/.azureml, alternatively + # see help for `workspace`. + ws <- workspace() + + # Really simple example: + add <- function(x,y) x + y + endpoint <- publishWebService(ws, + fun = add, + name = "addme", + inputSchema = list(x="numeric", + y="numeric"), + outputSchema = list(ans="numeric")) + consume(endpoint, list(x=pi, y=2)) + + + # A neat trick to evaluate any expression in the Azure ML virtual + # machine R session and view its output: + ep <- publishWebService(ws, + fun = function(expr) { + paste(capture.output( + eval(parse(text=expr))), collapse="\\n") + }, + name="commander", + inputSchema = list(x = "character"), + outputSchema = list(ans = "character")) + cat(consume(ep, list(x = "getwd()"))$ans) + cat(consume(ep, list(x = ".packages(all=TRUE)"))$ans) + cat(consume(ep, list(x = "R.Version()"))$ans) + + + # The following example illustrates scoping rules. Note that the function + # refers to the variable y defined outside the function body. That value + # will be exported with the service. + y <- pi + ep <- publishWebService(ws, + fun = function(x) x + y, + name = "lexi", + inputSchema = list(x = "numeric"), + outputSchema = list(ans = "numeric")) + cat(consume(ep, list(x=2))$ans) + + + # Example showing the use of consume to score all the rows of a data frame + # at once. The columns of the data frame correspond to the input parameters + # of the web service. + f <- function(a,b,c,d) list(sum = a+b+c+d, prod = a*b*c*d) + ep <- publishWebService(ws, + f, + name = "rowSums", + inputSchema = list( + a="numeric", + b="numeric", + c="numeric", + d="numeric" + ), + outputSchema = list( + sum ="numeric", + prod = "numeric") + ) + x <- head(iris[,1:4]) # First four columns of iris + + # Note the following will FAIL because of a name mismatch in the arguments + # (with an informative error): + consume(ep, x, retryDelay=1) + # We need the columns of the data frame to match the inputSchema: + names(x) <- letters[1:4] + # Now we can evaluate all the rows of the data frame in one call: + consume(ep, x) + # output should look like: + # sum prod + # 1 10.2 4.998 + # 2 9.5 4.116 + # 3 9.4 3.9104 + # 4 9.4 4.278 + # 5 10.2 5.04 + # 6 11.4 14.3208 + } } \seealso{ diff --git a/man/services.Rd b/man/services.Rd index 28bb0e8..0457eaa 100644 --- a/man/services.Rd +++ b/man/services.Rd @@ -13,11 +13,9 @@ getWebServices(ws, service_id, name, \arguments{ \item{ws}{An AzureML workspace reference returned by \code{\link{workspace}}.} -\item{service_id}{optional web service id. If supplied, return the web service information for just -the specified service id. Leave undefined to return a data.frame of all services.} +\item{service_id}{optional web service id. If supplied, return the web service information for just the specified service id. Leave undefined to return a data.frame of all services.} -\item{name}{optional web service name. If supplied, return the web service information for services -with matching names. Leave undefined to return all services.} +\item{name}{optional web service name. If supplied, return the web service information for services with matching names. Leave undefined to return all services.} \item{uri}{the AzureML web services URI} } @@ -43,7 +41,7 @@ The result is cached in the workspace environment similarly to datasets and expe \examples{ \dontrun{ workspace_id <- "" # Your AzureML workspace id -authorization_token <- "" # Your AsureML authorization token +authorization_token <- "" # Your AzureML authorization token ws <- workspace( id = workspace_id,