There are a lot of I-O functions in the Wolfram cloud and I'm getting confused between them. Can someone give a definitive answer as to when to use one or the other?
This is largely answered by this guide page: https://reference.wolfram.com/language/guide/CloudFunctionsAndDeployment.html
But I'll give a slightly expanded version of that.
You can think of the I-O cloud functions by putting them into two groups:
- functions that mirror the conventional file system counterparts (Put to CloudPut, Save to CloudSave, etc)
- functions that create web-based deployments that use server-side evaluations of user code
Or put simpler, functions that create static (every request gets the same thing) and dynamic content (every request triggers computation that can produce a different result each time).
Creating Static Content
CloudExport - if you want to convert an expression to a file format
CopyFile["local", CloudObject[...]] - if you want to upload a file as-is from the local file system to a cloud object.
CopyDirectory["localdir", CloudObject[...]] - if you want to upload a directory on the local file system to a cloud directory.
CreateDirectory[CloudObject[...]] - if you want to make a directory in the cloud file system
Reading Static Content
CloudGet - load and evaluate the contents of an expression
CloudImport - read a cloud object stored in a given format and convert it to an expression
CopyFile[CloudObject[...], "localfile"] - if you want to download a cloud object to the local file system
CopyDirectory[CloudObject[...], "localdir"] - if you want to download a directory of cloud objects to the local file system
URLRead - load a static resource via an HTTP request, where the contents are available in the response body
URLExecute - load a static resource via an HTTP request an import the result based on the MIME type of the response
Creating Dynamic Content
There's really two nearly identical functions for this, CloudDeploy and CloudPublish. They differ mainly in the default permissions, CloudPublish makes a public copy (anyone can access the cloud object without having to log in) and CloudDeploy uses $Permissions which is set to private by default.
The name "Deploy" in CloudDeploy is related to the previous concept of Deployed, which made user interface elements act in more of "delivered end-user product" way rather than a development environment, editable way.
CloudPublish has two usages that CloudDeploy doesn't have,
CloudPublish[obj] which are for publishing notebooks. If you evaluate
CloudPublish in a cloud notebook, it publishes the current notebook. If you evaluate
CloudObject[obj] it publishes a copy of the given cloud object.
Other than that, the main use of CloudDeploy and CloudPublish is to deploy dynamic content according to the expression argument you give it:
CloudDeploy[APIFunction[...]] if you want an API endpoint, designed for being called by another program.
CloudDeploy[FormFunction[...]] if you want a web form, for use by humans.
CloudDeploy[ScheduledTask[...]] if you want an evaluation that runs in the background, either on a schedule or on-demand with
There are quite a few of these special "heads", which we call "active heads". They include
AutoRefreshed (a variant of
DocumentGenerator (another variant of
CloudDeploy[expr] where expr is not one of the above heads if you want a notebook containing expr, which can contain Dynamic content.
Finally I'll note that in the comments the original poster mentioned "Share", which I take to mean
CloudShare, and that is not so much a direct I/O function as a function for modifying permissions and maintaining a "sharing list", which is some metadata that helps you know what documents you have shared with other users.
So, on top of all these functions to read and write cloud objects, there are a variety of bits of meta-information, which you can see with Options on a cloud object and with Information.