DOCS-1088: Pt3: Add to and fix cloud API (#1890)

viamrobotics · Sep 25, 2023 · c19039c · c19039c
1 parent 16fe56c
commit c19039c
Show file tree

Hide file tree

Showing 2 changed files with 260 additions and 12 deletions.
diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md
@@ -46,11 +46,12 @@ from viam.app.viam_client import ViamClient
 
 async def connect() -> ViamClient:
     dial_options = DialOptions(
-        # The URL of a robot in the location.
-        auth_entity='mrroboto.this_is_just_an_example.viam.cloud',
+        # The URL of any robot in the location.
+        auth_entity='beepboop-main.YOUR LOCATION ID.viam.cloud',
         credentials=Credentials(
             type='robot-location-secret',
-            payload='YOUR LOCATION SECRET'  # The location secret
+            # The location secret
+            payload='YOUR LOCATION SECRET'
         )
     )
     return await ViamClient.create_from_dial_options(dial_options)
@@ -60,8 +61,7 @@ async def main():
 
     # Make a ViamClient
     viam_client = await connect()
-    # Instantiate an AppClient called "cloud" to run the cloud app API methods
-    # on
+    # Instantiate an AppClient called "cloud" to run cloud app API methods on
     cloud = viam_client.app_client
 
     viam_client.close()
@@ -445,10 +445,6 @@ Delete a location secret.
 
 - `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
 
-**Returns:**
-
-- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str):
-
 ```python {class="line-numbers linkable-line-numbers"}
 await cloud.delete_location_secret(
     secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz")
@@ -461,7 +457,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 
 ### GetRobot
 
-Get a robot by its ID.
+Get a {{< glossary_tooltip term_id="robot" text="robot" >}} by its ID.
 
 {{< tabs >}}
 {{% tab name="Python" %}}
@@ -472,11 +468,11 @@ Get a robot by its ID.
 
 **Raises:**
 
-- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+- `GRPCError`: This error is raised if an invalid robot ID is passed.
 
 **Returns:**
 
-- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The robot.
+- [(viam.proto.app.Robot)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Robot): The robot.
 
 ```python {class="line-numbers linkable-line-numbers"}
 robot = await cloud.get_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")
@@ -487,6 +483,250 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
 {{% /tab %}}
 {{< /tabs >}}
 
+### GetRobotParts
+
+Get a list of all the {{< glossary_tooltip term_id="part" text="parts" >}} under a specific {{< glossary_tooltip term_id="robot" text="robot" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot to get parts from.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot ID is passed.
+
+**Returns:**
+
+- (List[[viam.app.app_client.RobotPart]](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.RobotPart)): The list of robot parts.
+
+```python {class="line-numbers linkable-line-numbers"}
+list_of_parts = await cloud.get_robot_parts(
+    robot_id="1a123456-x1yz-0ab0-a12xyzabc")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_robot_parts).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetRobotPart
+
+Get a specific robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_part_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot part to get.
+- `dest` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional filepath to write the robot part’s config in JSON format to.
+- `indent` [(int)](https://docs.python.org/3/library/functions.html#int): Size (in number of spaces) of indent when writing the JSON config to `dest`.
+  Defaults to `4`.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot ID is passed.
+
+**Returns:**
+
+- [(viam.app.app_client.RobotPart)](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.RobotPart): The robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+```python {class="line-numbers linkable-line-numbers"}
+my_robot_part = await cloud.get_robot_part(
+    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_robot_part).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetRobotPartLogs
+
+Get the logs associated with a specific robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_part_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot part to get logs from.
+- `filter` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Only include logs with messages that contain the string `filter`.
+  Defaults to empty string `""`, meaning no filter.
+- `dest` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional filepath to write the log entries to.
+- `errors_only` [(bool)](https://docs.python.org/3/library/functions.html#bool): Specifies whether to limit returned log messages to error logs only.
+  Defaults to `True`, including only error-level messages by default.
+- `num_log_entries` [(int)](https://docs.python.org/3/library/functions.html#int): Number of log entries to return.
+  Passing `0` returns all logs.
+  Defaults to `100`.
+  All logs or the first `num_log_entries` logs will be returned, whichever comes first.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot part ID is passed.
+
+**Returns:**
+
+- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The list of log entries.
+
+```python {class="line-numbers linkable-line-numbers"}
+part_logs = await cloud.get_robot_part_logs(
+    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22", num_log_entries=20)
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_robot_part_logs).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### TailRobotPartLogs
+
+Get an asynchronous iterator that receives live robot part logs.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_part_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot part to retrieve logs from.
+- `errors_only` [(bool)](https://docs.python.org/3/library/functions.html#bool): Specifies whether to limit returned log messages to error logs only.
+  Defaults to `True`, including only error-level messages by default.
+- `filter` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Only include logs with messages that contain the string `filter`.
+  Defaults to empty string `""`, meaning no filter.
+
+**Returns:**
+
+- (_LogsStream[[List[LogEntry]]](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.LogEntry)): The asynchronous iterator receiving live robot part logs.
+
+```python {class="line-numbers linkable-line-numbers"}
+logs_stream = await cloud.tail_robot_part_logs(
+    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.tail_robot_part_logs).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetRobotPartHistory
+
+Get a list containing the history of a robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_part_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot part to retrieve history from.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot part ID is passed.
+
+**Returns:**
+
+- (List[[viam.app.app_client.RobotPartHistoryEntry](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.RobotPartHistoryEntry)]): The list of the robot part’s history.
+
+```python {class="line-numbers linkable-line-numbers"}
+part_history = await cloud.get_robot_part_history(
+    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_robot_part_history).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### UpdateRobotPart
+
+Change the name of and assign an optional new configuration to a robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_part_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot part to update.
+- `name` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): New name to be updated on the robot part.
+- `robot_config` (Mapping[str, Any]): Optional new config represented as a dictionary to be updated on the robot part.
+  The robot part's config remains unchanged if a new `robot_config` is not passed.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot part ID, name, or config is passed.
+
+**Returns:**
+
+- [(viam.app.app_client.RobotPart)](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.RobotPart): The newly-updated robot part.
+
+```python {class="line-numbers linkable-line-numbers"}
+my_robot_part = await cloud.update_robot_part(
+    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.update_robot_part).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### NewRobotPart
+
+Create a new robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot to create a new part for.
+- `part_name` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Name of the new part.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot ID is passed.
+
+**Returns:**
+
+- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The new robot part’s ID.
+
+```python {class="line-numbers linkable-line-numbers"}
+new_part_id = await cloud.new_robot_part(
+    robot_id="1a123456-x1yz-0ab0-a12xyzabc", part_name="myNewSubPart")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.new_robot_part).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### DeleteRobotPart
+
+Delete the specified robot {{< glossary_tooltip term_id="part" text="part" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_part_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot part to delete.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid robot part ID is passed.
+
+```python {class="line-numbers linkable-line-numbers"}
+await cloud.delete_robot_part(
+    robot_part_id="abc12345-1a23-1234-ab12-a22a22a2aa22")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.delete_robot_part).
+
+{{% /tab %}}
+{{< /tabs >}}
+
 ### NewRobot
 
 Create a new {{< glossary_tooltip term_id="robot" text="robot" >}}.

diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md
@@ -13,4 +13,12 @@ Method Name | Description
 [`CreateLocationSecret`](/program/apis/cloud/#createlocationsecret ) | Create a new location secret.
 [`DeleteLocationSecret`](/program/apis/cloud/#deletelocationsecret ) | Delete a location secret.
 [`GetRobot`](/program/apis/cloud/#getrobot ) | Get a robot by robot ID.
+[`GetRobotParts`](/program/apis/cloud/#getrobotparts ) | Get a list of all the {{< glossary_tooltip term_id="part" text="parts" >}} under a specific robot.
+[`GetRobotPart`](/program/apis/cloud/#getrobotpart ) | Get a robot {{< glossary_tooltip term_id="part" text="part" >}}.
+[`GetRobotPartLogs`](/program/apis/cloud/#getrobotpartlogs ) | Get the logs associated with a robot part.
+[`TailRobotPartLogs`](/program/apis/cloud/#tailrobotpartlogs ) | Get an asynchronous iterator that receives live robot part logs.
+[`GetRobotPartHistory`](/program/apis/cloud/#getrobotparthistory ) | Get a list containing the history of a robot part.
+[`UpdateRobotPart`](/program/apis/cloud/#updaterobotpart ) | Update the name or configuration of a robot part.
+[`NewRobotPart`](/program/apis/cloud/#newrobotpart ) | Create a new robot part.
+[`DeleteRobotPart`](/program/apis/cloud/#deleterobotpart ) | Delete a robot part.
 [`NewRobot`](/program/apis/cloud/#newrobot ) | Create a new robot.