diff --git a/source/includes/api-details/cpp/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/cpp/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..debb2b5729 --- /dev/null +++ b/source/includes/api-details/cpp/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,8 @@ +To call an Atlas Function, use the +:cpp-sdk:`call_function() ` +member function on the ``user`` object. Pass in the name of the +function as a string for the first parameter. This function takes two arguments, +which we provide as a string array of arguments. + +The callback can provide an optional string result, or an optional error. +In this example, we check that the result has a value. diff --git a/source/includes/api-details/csharp/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/csharp/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..e613ba25ce --- /dev/null +++ b/source/includes/api-details/csharp/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,23 @@ +To call an Atlas Function, use the +:dotnet-sdk:`Functions.CallAsync() ` +method on the ``User`` object, passing in the name of the function as the first +parameter and the arguments as the remaining parameters: + +.. literalinclude:: /examples/generated/dotnet/FunctionExamples.snippet.callfunc.cs + :language: csharp + +.. note:: + + The ``CallAsync()`` method returns a single ``BsonValue`` object, which you can + deserialize after calling the function or by using the generic + overload. Both of these approaches to deserialization are shown in the + code above. + +A ``BsonValue`` object can hold a single primitive value (as shown in the +example above), or hold a complete BSON document. If +you have a class that maps to the returned object, you can deserialize +to that class by using the generic overload. For example, the following code +calls a function that returns an object from a collection of "RealmTasks". +Since we know the shape of the returned object, we we can deserialize the +``BsonValue`` to a class that we have created, and then we have +access to the properties and methods on that object: diff --git a/source/includes/api-details/dart/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/dart/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..50c3d28692 --- /dev/null +++ b/source/includes/api-details/dart/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,11 @@ +To call a Function, call :flutter-sdk:`User.functions.call() `. +Pass the Function name as the first argument and all arguments for the Function +in a List as the second argument. + +To include objects as arguments to the Function, +convert them to JSON first. You can do this using the `jsonEncode() +`__ +function included in the built-in ``dart:convert`` library. + +The Function returns a ``dynamic`` value containing :manual:`MongoDB Extended JSON (EJSON) +` deserialized to a native Dart object. diff --git a/source/includes/api-details/java/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/java/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..c1dd254832 --- /dev/null +++ b/source/includes/api-details/java/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,8 @@ +To execute a function from the SDK, use the +:java-sdk:`getFunctions() ` +method of the your :java-sdk:`App ` +to retrieve a :java-sdk:`Functions manager `. + +Pass the name and parameters of the function you would like to call to +:java-sdk:`callFunction() ` +or :java-sdk:`callFunctionAsync() `: diff --git a/source/includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst b/source/includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst new file mode 100644 index 0000000000..b696350cfe --- /dev/null +++ b/source/includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst @@ -0,0 +1,3 @@ +To call a function, you can either pass its name and arguments to +``User.callFunction()`` or call the function as if it was a method on the +:js-sdk:`User.functions ` property. diff --git a/source/includes/api-details/kotlin/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/kotlin/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..813667d119 --- /dev/null +++ b/source/includes/api-details/kotlin/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,7 @@ +To call an Atlas Function, pass its name and all arguments to +:kotlin-sync-sdk:`Functions.call() `. + +You can serialize Function arguments and return values using an EJSON encoder. +For more information, including examples, refer to :ref:`sdks-ejson-encoding-for-atlas`. + +To call this Atlas Function from the SDK: diff --git a/source/includes/api-details/objectivec/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/objectivec/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..f44365592d --- /dev/null +++ b/source/includes/api-details/objectivec/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,6 @@ +To execute a function in Objective-C, call the :objc-sdk:`callFunctionNamed:arguments:completionBlock: +`. +method on the :objc-sdk:`RLMUser ` object. + +Provide the Function name, arguments, and completion block to execute when the +Function call is complete. diff --git a/source/includes/api-details/swift/atlas/call-atlas-function-call-function-description.rst b/source/includes/api-details/swift/atlas/call-atlas-function-call-function-description.rst new file mode 100644 index 0000000000..b27ba672b3 --- /dev/null +++ b/source/includes/api-details/swift/atlas/call-atlas-function-call-function-description.rst @@ -0,0 +1,18 @@ +To execute a function in Swift, use the :swift-sdk:`functions +` object on the currently logged-in user. + +The ``functions`` object has dynamic members corresponding to functions. +In this case, ``functions.concatenate()`` refers to the ``concatenate`` +function. Pass a ``BSONArray`` of arguments. + +Async/Await +``````````` + +.. literalinclude:: /examples/generated/code/start/Functions.snippet.async-call-a-function.swift + :language: swift + +Completion Handler +`````````````````` + +The trailing closure is the completion handler to call when the function call +is complete. This handler is executed on a non-main global ``DispatchQueue``. diff --git a/source/includes/important-sanitize-client-data-in-functions.rst b/source/includes/important-sanitize-client-data-in-functions.rst deleted file mode 100644 index ba905434f5..0000000000 --- a/source/includes/important-sanitize-client-data-in-functions.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. important:: - - Make sure to sanitize client data to protect against code injection when using - Functions. \ No newline at end of file diff --git a/source/includes/sdk-examples/atlas/call-atlas-function-call-function.rst b/source/includes/sdk-examples/atlas/call-atlas-function-call-function.rst new file mode 100644 index 0000000000..f227b13d30 --- /dev/null +++ b/source/includes/sdk-examples/atlas/call-atlas-function-call-function.rst @@ -0,0 +1,80 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/call-function.snippet.call-a-function.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FunctionExamples.snippet.callfuncWithPOCO.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/functions_test.snippet.call-function.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FunctionTest.snippet.call-a-function.java + :language: java + :emphasize-lines: 10-17 + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FunctionTest.snippet.call-a-function.kt + :language: kotlin + :emphasize-lines: 8,9,10,11,12,13,14,15,16,17 + + - id: javascript + content: | + + .. io-code-block:: + + .. input:: /examples/generated/node/call-a-function.snippet.call-a-function-by-name.js + :language: javascript + + .. output:: + :language: console + + Using the "functions.sum()" method: the sum of 2 + 3 = 5 + Using the "callFunction()" method: the sum of 2 + 3 = 5 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/FunctionsTest.snippet.call-function.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/Functions.snippet.call-a-function.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Functions.snippet.call-a-function.swift + :language: swift + + - id: typescript + content: | + + .. io-code-block:: + + .. input:: /examples/generated/node/call-a-function.snippet.call-a-function-by-name.js + :language: javascript + + .. output:: + :language: console + + Using the "functions.sum()" method: the sum of 2 + 3 = 5 + Using the "callFunction()" method: the sum of 2 + 3 = 5 diff --git a/source/sdk/atlas/call-function.txt b/source/sdk/atlas/call-function.txt index c31a89ed61..c96db002b3 100644 --- a/source/sdk/atlas/call-function.txt +++ b/source/sdk/atlas/call-function.txt @@ -1,13 +1,107 @@ .. _sdks-call-function: -=============== -Call a Function -=============== +====================== +Call an Atlas Function +====================== + +.. meta:: + :description: Call serverless Atlas Functions from a client application with Atlas Device SDK. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, objective-c, swift .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 1 :class: singlecol -Placeholder page for the call a Function content. +.. tabs-selector:: drivers + +You can call an **Atlas Function** from a client application using Atlas +Device SDK. Functions are serverless JavaScript functions that let you define +and execute server-side logic. These server-side Functions can run in the +context of the authenticated user, and thus honor the rules, roles, and +permissions that you have assigned to your data in Atlas. + +For more information on configuring and writing Atlas Functions, refer to +:ref:`Atlas Functions ` in the App Services documentation. + +Before You Begin +---------------- + +#. In an App Services App, :ref:`define an Atlas Function `. +#. In your client project, :ref:`initialize the App client `. +#. Then, :ref:`authenticate a user `. You access + Functions through the user object. + +The example on this page demonstrates calling an :ref:`Atlas Function ` +that takes two arguments, performs some work, and returns the result. + +Call a Function +--------------- + +.. important:: + + Make sure to sanitize client data to protect against code injection when using + Functions. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/atlas/call-atlas-function-call-function-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/atlas/call-atlas-function-call-function-js-ts-description.rst + +.. include:: /includes/sdk-examples/atlas/call-atlas-function-call-function.rst diff --git a/source/sdk/serialization.txt b/source/sdk/serialization.txt index fbbc0e03e5..0fe8d69edf 100644 --- a/source/sdk/serialization.txt +++ b/source/sdk/serialization.txt @@ -11,3 +11,8 @@ Serialization :class: singlecol Placeholder page for information about serialization in the SDKs. + +.. _sdks-ejson-encoding-for-atlas: + +EJSON Encoding +--------------