more doc

CONTRIBUTING.md

@@ -0,0 +1,14 @@
+
+# Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.

R/az_cogsvc.R

@@ -6,9 +6,9 @@
 #' @section Methods:
 #' The following methods are available, in addition to those provided by the [AzureRMR::az_resource] class:
 #' - `list_keys()`: Return the access keys for this service.
-#' - `get_endpoint(key)`: Return the service endpoint, along with an access key. See 'Endpoints' below.
+#' - `get_endpoint()`: Return the service endpoint, along with an access key. See 'Endpoints' below.
 #' - `regen_key(key)`: Regenerates (creates a new value for) an access key. The argument `key` can be 1 or 2.
-#' - `list_skus()`: List the SKUs (pricing tiers) available for this service.
+#' - `list_service_tiers()`: List the service pricing tiers (SKUs) available for this service.
 #'
 #' @section Initialization:
 #' Initializing a new object of this class can either retrieve an existing service, or create a new service on the host. Generally, the best way to initialize an object is via the `get_cognitive_service` and `create_cognitive_service` methods of the [az_resource_group] class, which handle the details automatically.
@@ -33,7 +33,7 @@ public=list(
         unlist(private$res_op("regenerateKey", body=body, http_verb="POST"))
     },
 
-    list_skus=function()
+    list_service_tiers=function()
     {
         private$res_op("skus")$value
     },

README.md

@@ -1,14 +1,43 @@
+# AzureCognitive
 
-# Contributing
+A package to work with [Azure Cognitive Services](https://azure.microsoft.com/services/cognitive-services/). Both a Resource Manager interface and a client interface to the REST API are provided.
 
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+## Resource Manager interface
 
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+AzureCognitive extends the class framework provided by [AzureRMR](https://github.com/Azure/AzureRMR) to support Cognitive Services. You can create, retrieve, update, and delete cognitive service resources by calling the corresponding methods for a resource group.
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+```r
+az <- AzureRMR::get_azure_login()
+sub <- az$get_subscription("sub_id")
+rg <- sub$get_resource_group("rgname")
+
+# create a new Computer Vision service
+rg$create_cognitive_service("myvisionservice",
+    service_type="ComputerVision", service_tier="S1")
+
+cogsvc <- rg$get_cognitive_service("myvisionservice")
+
+# list subscription keys
+cogsvc$list_keys()
+```
+
+## Client interface
+
+AzureCognitive implements basic functionality for communicating with a cognitive service endpoint. It is meant to be used by other packages to support specific services, like Computer Vision, LUIS (language understanding), etc.
+
+```r
+# getting the endpoint from the resource object
+endp <- cogsvc$get_endpoint()
+
+# or standalone (must provide subscription key)
+endp <- cognitive_endpoint("https://myvisionservice.cognitiveservices.azure.com/",
+    service_type="ComputerVision", key="key")
+
+# analyze an image
+img_link <- "http://news.microsoft.com/uploads/2014/09/billg1_print.jpg"
+call_cognitive_endpoint(endp,
+    operation="analyze",
+    body=list(url=img_link),
+    options=list(details="celebrities"),
+    http_verb="POST")
+```