From 7d1fbed9a767ca6c61be91196476a5d79ea1228c Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Thu, 14 Sep 2023 11:26:46 -0400 Subject: [PATCH] DOCS-1088: Document more of the cloud API (#1814) --- docs/program/apis/cloud.md | 290 +++++++++++++++++++++++++- static/include/services/apis/cloud.md | 11 +- 2 files changed, 295 insertions(+), 6 deletions(-) diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md index 459edc7203..9c4d0990ed 100644 --- a/docs/program/apis/cloud.md +++ b/docs/program/apis/cloud.md @@ -67,7 +67,7 @@ The cloud API supports the following methods (among [others](https://python.viam ### ListOrganizations -List the organizations the user is an authorized user of. +List the {{< glossary_tooltip term_id="organization" text="organizations" >}} the user is an authorized user of. {{< tabs >}} {{% tab name="Python" %}} @@ -91,7 +91,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### ListOrganizationMembers -List the members and invites of the organization that you are currently authenticated to. +List the members and invites of the {{< glossary_tooltip term_id="organization" text="organizations" >}} that you are currently authenticated to. {{< tabs >}} {{% tab name="Python" %}} @@ -117,7 +117,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ### GetOrganizationNamespaceAvailability -Check the availability of an organization namespace. +Check the availability of an {{< glossary_tooltip term_id="organization" text="organization" >}} namespace. {{< tabs >}} {{% tab name="Python" %}} @@ -188,9 +188,289 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ {{% /tab %}} {{< /tabs >}} +### CreateLocation + +Create and name a {{< glossary_tooltip term_id="location" text="location" >}} under the organization you are currently authenticated to. +Optionally, put the new location under a specified parent location. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `name` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Name of the new location. +- `parent_location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional parent location to put the location under. +Defaults to creating a location in your organization at root level if you do not provide a location ID. + +**Raises:** + +- `GRPCError`: This error is raised if an invalid name (such as "") or invalid parent location ID is passed. + +**Returns:** + +- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly created location. + +```python {class="line-numbers linkable-line-numbers"} +my_new_location = await cloud.create_location(name="Robotville", parent_location_id="111ab12345") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.create_location). + +{{% /tab %}} +{{< /tabs >}} + +### GetLocation + +Get a {{< glossary_tooltip term_id="location" text="location" >}} by its location ID. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to get. +Defaults to the location ID provided at `AppClient` instantiation. + +**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. + +**Returns:** + +- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID. + +```python {class="line-numbers linkable-line-numbers"} +location = await cloud.get_location(location_id="123ab12345") +``` + +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_location). + +{{% /tab %}} +{{< /tabs >}} + +### UpdateLocation + +Change the name of a {{< glossary_tooltip term_id="location" text="parent location" >}} and/or assign it a new location. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to update. +- `name` [Optional(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional new name to update the location name to. +If nothing is passed, the name is not changed. +- `parent_location_id` [Optional(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional ID of the new location to move the location to. +If nothing is passed, the location does not move. +If an empty string is passed, the location moves up to the top level. + +**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. + +**Returns:** + +- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly updated location. + +```python {class="line-numbers linkable-line-numbers"} +# The following line takes the location with ID "abc12abcde" and moves it +# to be a sub-location of the location with ID "xyz34xxxxx" +my_updated_location = await cloud.update_location( + location_id="abc12abcde", + name="", + parent_location_id="xyz34xxxxx", +) + +# The following line changes the name of the location without changing its parent location +my_updated_location = await cloud.update_location( + location_id="abc12abcde", + name="Land Before Robots" +) + +# The following line moves the location back up to be a top level location without changing its name +my_updated_location = await cloud.update_location( + location_id="abc12abcde", + name="", + parent_location_id="" +) +``` + +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_location). + +{{% /tab %}} +{{< /tabs >}} + +### DeleteLocation + +Delete a {{< glossary_tooltip term_id="location" text="location" >}}. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete. + +**Raises:** + +- `GRPCError`: This error is raised if an invalid location ID is passed. + +**Returns:** + +- None + +```python {class="line-numbers linkable-line-numbers"} +await cloud.delete_location(location_id="abc12abcde") +``` + +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_location). + +{{% /tab %}} +{{< /tabs >}} + +### ListLocations + +Get a list of all {{< glossary_tooltip term_id="location" text="locations" >}} under the organization you are currently authenticated to. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None + +**Returns:** + +- (List[[viam.proto.app.Location](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location)]): The list of locations. + +```python {class="line-numbers linkable-line-numbers"} +locations = await cloud.list_locations() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.list_locations). + +{{% /tab %}} +{{< /tabs >}} + +### LocationAuth + +Get a location’s `LocationAuth` (location secret or secrets). + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to retrieve `LocationAuth` from. +Defaults to the location ID provided at `AppClient` instantiation. + +**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. + +**Returns:** + +- [(viam.proto.app.LocationAuth)](https://python.viam.dev/autoapi/viam/gen/app/v1/app_pb2/index.html#viam.gen.app.v1.app_pb2.LocationAuth): The `LocationAuth` containing location secrets and secret IDs. + +```python {class="line-numbers linkable-line-numbers"} +loc_auth = await cloud.location_auth(location_id="123xy12345") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.location_auth). + +{{% /tab %}} +{{< /tabs >}} + +### CreateLocationSecret + +Create a new location secret. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to generate a new secret for. + Defaults to the location ID provided at `AppClient` instantiation. + +**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. + +**Returns:** + +- [(viam.proto.app.LocationAuth)](https://python.viam.dev/autoapi/viam/gen/app/v1/app_pb2/index.html#viam.gen.app.v1.app_pb2.LocationAuth): The specified location's `LocationAuth` containing the newly created secret. + +```python {class="line-numbers linkable-line-numbers"} +new_loc_auth = await cloud.create_location_secret() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.create_location_secret). + +{{% /tab %}} +{{< /tabs >}} + +### DeleteLocationSecret + +Delete a location secret. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete the secret from. + Defaults to the location ID provided at `AppClient` instantiation. +- `secret_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The `id` of the secret to delete (not the secret string itself). + +**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. + +**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") +``` + +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_location_secret). + +{{% /tab %}} +{{< /tabs >}} + +### GetRobot + +Get a robot by its ID. + +{{< 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. + +**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. + +**Returns:** + +- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The robot. + +```python {class="line-numbers linkable-line-numbers"} +robot = await cloud.get_robot(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). + +{{% /tab %}} +{{< /tabs >}} + ### NewRobot -Create a new robot. +Create a new {{< glossary_tooltip term_id="robot" text="robot" >}}. {{< tabs >}} {{% tab name="Python" %}} @@ -213,7 +493,7 @@ Create a new robot. new_robot_id = await cloud.new_robot(name="beepboop") ``` -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_organization_namespace_availability). +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). {{% /tab %}} {{< /tabs >}} diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md index 11c1df13e4..3d8ec8fa80 100644 --- a/static/include/services/apis/cloud.md +++ b/static/include/services/apis/cloud.md @@ -4,4 +4,13 @@ Method Name | Description [`GetOrganizationNamespaceAvailability`](/program/apis/cloud/#getorganizationnamespaceavailability) | Check the availability of an organization namespace. [`ListOrganizationMembers`](/program/apis/cloud/#listorganizationmembers) | List the members and invites of the current organization. [`UpdateOrganizationInviteAuthorizations`](/program/apis/cloud/#updateorganizationinviteauthorizations) | Update the authorizations attached to an organization invite that has already been created. -[`NewRobot`](/program/apis/cloud/# ) | Create a new robot. +[`CreateLocation`](/program/apis/cloud/#createlocation) | Create and name a location. +[`GetLocation`](/program/apis/cloud/#getlocation) | Get a location by its ID. +[`UpdateLocation`](/program/apis/cloud/#updatelocation ) | Change the name of and/or assign a parent location to a location. +[`DeleteLocation`](/program/apis/cloud/#deletelocation ) | Delete a location. +[`ListLocations`](/program/apis/cloud/#listlocations ) | List locations. +[`LocationAuth`](/program/apis/cloud/#locationauth ) | Get a location's authorization (location secrets). +[`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. +[`NewRobot`](/program/apis/cloud/#newrobot ) | Create a new robot.