Skip to content

Commit 0dde753

Browse files
charceycharcey
authored
Update docs for Destinations API and add CLI tests (#1176)
* make source type truly optional for planetary_variable_source * complete cli docs * Revert "make source type truly optional for planetary_variable_source" This reverts commit aa6dba8. * readme update * test fixes
1 parent aa17791 commit 0dde753

File tree

7 files changed

+462
-1
lines changed

7 files changed

+462
-1
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Version 2.0 includes support for the core workflows of the following APIs:
1515
* [Orders](https://docs.planet.com/develop/apis/orders/) - Process and download or deliver imagery.
1616
* [Subscriptions](https://docs.planet.com/develop/apis/subscriptions/) - Set up a search to auto-process and deliver imagery.
1717
* [Features](https://docs.planet.com/develop/apis/features/) - Upload areas of interest to the Planet platform.
18+
* [Destinations] (https://docs.planet.com/develop/apis/destinations/) - Create destinations to securely store cloud credentials.
1819

1920
After the initial 2.0 release there will be additional work to support the
2021
remaining Planet APIs: [basemaps](https://docs.planet.com/develop/apis/basemaps/),

‎design-docs/CLI-Core.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ subscriptions.
1515
* [Orders](CLI-Orders.md)
1616
* [Data](CLI-Data.md)
1717
* [Subscriptions](CLI-Subscriptions.md)
18+
* [Destinations](CLI-Destinations.md)
1819

1920
## CLI Base
2021

‎design-docs/CLI-Destinations.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
# Destinations Command-Line Interface Specification
2+
3+
This document lays out the command-line interface to interact with the Planet
4+
[Destinations API](https://docs.planet.com/develop/apis/destinations/).
5+
6+
## Overview
7+
8+
The `planet destinations` command group allows you to list, create, update, archive, unarchive, and rename cloud storage destinations, including Amazon S3, S3-compatible, Google Cloud Storage, Azure Blob Storage, and Oracle Cloud Storage.
9+
10+
---
11+
12+
## Global Options
13+
14+
- `-u, --base-url TEXT`
15+
Assign custom base Destinations API URL.
16+
17+
---
18+
19+
## Commands
20+
21+
### List Destinations
22+
23+
```sh
24+
planet destinations list [OPTIONS]
25+
```
26+
27+
**Options:**
28+
- `--archived [true|false]`
29+
Include only archived destinations (`true`) or exclude them (`false`).
30+
- `--is-owner [true|false]`
31+
Include only destinations owned by the requesting user (`true`) or exclude them (`false`).
32+
- `--can-write [true|false]`
33+
Include only destinations the user can modify (`true`) or exclude them (`false`).
34+
35+
**Example:**
36+
```sh
37+
planet destinations list --archived false --is-owner true --can-write true
38+
```
39+
40+
---
41+
42+
### Get Destination
43+
44+
```sh
45+
planet destinations get DESTINATION_ID [OPTIONS]
46+
```
47+
48+
Retrieve detailed information about a specific destination.
49+
50+
**Example:**
51+
```sh
52+
planet destinations get my-destination-id
53+
```
54+
55+
---
56+
57+
### Create Destinations
58+
59+
#### Amazon S3
60+
61+
```sh
62+
planet destinations create s3 --bucket BUCKET --region REGION --access-key-id KEY --secret-access-key SECRET [--explicit-sse] [--name NAME]
63+
```
64+
65+
**Options:**
66+
- `--bucket` (required): S3 bucket name.
67+
- `--region` (required): AWS region.
68+
- `--access-key-id` (required): AWS access key ID.
69+
- `--secret-access-key` (required): AWS secret access key.
70+
- `--explicit-sse`: Explicitly set headers for server-side encryption (SSE).
71+
- `--name`: Optional name for the destination.
72+
73+
#### S3-Compatible
74+
75+
```sh
76+
planet destinations create s3-compatible --bucket BUCKET --endpoint ENDPOINT --region REGION --access-key-id KEY --secret-access-key SECRET [--use-path-style] [--name NAME]
77+
```
78+
79+
**Options:**
80+
- `--bucket` (required): Bucket name.
81+
- `--endpoint` (required): Endpoint URL.
82+
- `--region` (required): Region.
83+
- `--access-key-id` (required): Access key ID.
84+
- `--secret-access-key` (required): Secret access key.
85+
- `--use-path-style`: Use path-style addressing.
86+
- `--name`: Optional name for the destination.
87+
88+
#### Google Cloud Storage (GCS)
89+
90+
```sh
91+
planet destinations create gcs --bucket BUCKET --credentials BASE64_JSON [--name NAME]
92+
```
93+
94+
**Options:**
95+
- `--bucket` (required): GCS bucket name.
96+
- `--credentials` (required): Base64-encoded service account credentials (JSON).
97+
- `--name`: Optional name for the destination.
98+
99+
#### Azure Blob Storage
100+
101+
```sh
102+
planet destinations create azure --container CONTAINER --account ACCOUNT --sas-token SAS_TOKEN [--storage-endpoint-suffix SUFFIX] [--name NAME]
103+
```
104+
105+
**Options:**
106+
- `--container` (required): Blob storage container name.
107+
- `--account` (required): Azure account.
108+
- `--sas-token` (required): Shared-Access Signature token.
109+
- `--storage-endpoint-suffix`: Custom Azure Storage endpoint suffix.
110+
- `--name`: Optional name for the destination.
111+
112+
#### Oracle Cloud Storage (OCS)
113+
114+
```sh
115+
planet destinations create ocs --bucket BUCKET --access-key-id KEY --secret-access-key SECRET --namespace NAMESPACE --region REGION [--name NAME]
116+
```
117+
118+
**Options:**
119+
- `--bucket` (required): Oracle bucket name.
120+
- `--access-key-id` (required): Oracle account access key.
121+
- `--secret-access-key` (required): Oracle account secret key.
122+
- `--namespace` (required): Oracle Object Storage namespace.
123+
- `--region` (required): Oracle region.
124+
- `--name`: Optional name for the destination.
125+
126+
---
127+
128+
### Update Destinations
129+
130+
#### Amazon S3
131+
132+
```sh
133+
planet destinations update s3 DESTINATION_ID --access-key-id KEY --secret-access-key SECRET [--explicit-sse]
134+
```
135+
136+
#### S3-Compatible
137+
138+
```sh
139+
planet destinations update s3-compatible DESTINATION_ID --access-key-id KEY --secret-access-key SECRET [--use-path-style]
140+
```
141+
142+
#### Google Cloud Storage (GCS)
143+
144+
```sh
145+
planet destinations update gcs DESTINATION_ID --credentials BASE64_JSON
146+
```
147+
148+
#### Azure Blob Storage
149+
150+
```sh
151+
planet destinations update azure DESTINATION_ID --sas-token SAS_TOKEN
152+
```
153+
154+
#### Oracle Cloud Storage (OCS)
155+
156+
```sh
157+
planet destinations update ocs DESTINATION_ID --access-key-id KEY --secret-access-key SECRET
158+
```
159+
160+
---
161+
162+
### Archive/Unarchive Destinations
163+
164+
#### Archive
165+
166+
```sh
167+
planet destinations archive DESTINATION_ID
168+
```
169+
170+
#### Unarchive
171+
172+
```sh
173+
planet destinations unarchive DESTINATION_ID
174+
```
175+
176+
---
177+
178+
### Rename Destination
179+
180+
```sh
181+
planet destinations rename DESTINATION_ID NEW_NAME
182+
```
183+
184+
---
185+
186+
## Notes
187+
188+
- For GCS, the `--credentials` argument must be the base64-encoded JSON of your Google Cloud service account key.
189+
To encode a JSON file to base64:
190+
```sh
191+
cat my_creds.json | base64 | tr -d '\n'
192+
```
193+
194+
- All commands support the `--base-url` option for custom API endpoints.
195+
196+
---

‎docs/cli/cli-guide.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,8 @@ If you’re already comfortable with CLI tools you can safely skip this section.
1818
extensive examples.
1919
* **[CLI for Orders API](cli-orders.md)** dives into the `planet orders` commands
2020
with numerous samples to get you started.
21-
* **[CLI for Subscriptions API](cli-subscriptions.md)** - explains the `planet subscriptions` commands
21+
* **[CLI for Subscriptions API](cli-subscriptions.md)** - explains the `planet subscriptions` commands.
22+
* **[CLI for Destinations API](cli-destinations.md)** - explores the `planet destinations` commands with examples.
2223
* **[CLI Tips & Tricks](cli-tips-tricks.md)** highlights a number of interesting
2324
geospatial CLI command-line tools and shows you how to use them in conjunction
2425
with Planet’s tools.

‎docs/python/sdk-reference.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,14 @@ title: Python SDK API Reference
3838
rendering:
3939
show_root_full_path: false
4040

41+
## ::: planet.DestinationsClient
42+
rendering:
43+
show_root_full_path: false
44+
45+
## ::: planet.FeaturesClient
46+
rendering:
47+
show_root_full_path: false
48+
4149
## ::: planet.Planet
4250
rendering:
4351
show_root_full_path: false

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ nav:
8080
- cli/cli-data.md
8181
- cli/cli-orders.md
8282
- cli/cli-subscriptions.md
83+
- cli/cli-destinations.md
8384
- cli/cli-tips-tricks.md
8485
- cli/cli-reference.md
8586
- "Python":

0 commit comments

Comments
 (0)