Skip to content

Commit 746a8bc

Browse files
carl-adams-planetcarl-adams-planet
authored
Merge pull request #1179 from planetlabs/carl/update-3.0-from-main
Carl/update 3.0 from main
2 parents 4fa0002 + 87fa4a1 commit 746a8bc

24 files changed

+1720
-12
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-destinations.md

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: CLI for Destinations API Tutorial
3+
---
4+
5+
## Introduction
6+
The `planet destinations` command provides an interface for creating, listing, and modifying destinations in the [Planet Destinations API](https://docs.planet.com/develop/apis/destinations/). This tutorial takes you through the main commands available in the CLI.
7+
8+
## Core Workflows
9+
10+
### Create a Destination
11+
To discover supported cloud destinations, run the command `planet destinations create --help`. Once you have chosen your target cloud destination type, run the command `planet destinations create <type> --help` to discover the required and supported parameters (eg: `planet destinations create s3 --help`).
12+
13+
Finally, submit the full request:
14+
```sh
15+
planet destinations create s3 --bucket my-bucket --region us-west-2 --access-key-id AKIA... --secret-access-key SECRET... --name my-s3-destination
16+
```
17+
18+
The newly created destination will be printed to stdout, with the destination reference under the key `pl:ref`, which can subsequently be used in Orders API and Subscriptions API requests as the delivery destination.
19+
20+
### List Destinations
21+
List all destinations within your organization with command `planet destinations list`.
22+
23+
You can get nicer formatting with `--pretty` or pipe it into `jq`, just like the other Planet CLIs.
24+
25+
#### Filtering
26+
The `list` command supports filtering on a variety of fields. You can discover all filterable fields by running the command `planet destinations list --help`.
27+
28+
* `--archived`: Set to true to include only archived destinations,
29+
false to exclude them.
30+
* `--is-owner`: Set to true to include only destinations owned by the
31+
requesting user, false to exclude them.
32+
* `--can-write`: Set to true to include only destinations the user can
33+
modify, false to exclude them.
34+
35+
For example, issue the following command to list destinations that are not archived and you as the user have permission to modify:
36+
```sh
37+
planet destinations list --archived false --can-write true
38+
```
39+
40+
### Modify Destinations
41+
The CLI conveniently moves all modify actions to first class commands on the destination. The supported actions are archive, unarchive, rename, and update credentials. To discover all update actions run `planet destinations --help`.
42+
43+
To discover more information about a specific update action, use the `--help` flag (eg: `planet destinations rename --help`, `planet destinations update --help`).
44+
45+
Credential updating might be done if credentials expire or need to be rotated. For example, this is how s3 credentials would be updated.
46+
```sh
47+
planet destinations update s3 my-destination-id --access-key-id NEW_ACCESS_KEY --secret-access-key NEW_SECRET_KEY
48+
```
49+
50+
## Using destinations in Subscriptions API
51+
After creating a destination, it can be used as the delivery location for subscriptions. Use the destination reference in the delivery block instead of credentials.
52+
53+
The subsequent examples will use the destination ref `pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX`.
54+
```json
55+
{
56+
"name": "Subscription using a destination",
57+
"source": {
58+
"parameters": {
59+
"asset_types": [
60+
"ortho_analytic_8b"
61+
],
62+
"end_time": "2023-11-01T00:00:00Z",
63+
"geometry": {
64+
"coordinates": [
65+
[
66+
[
67+
139.5648193359375,
68+
35.42374884923695
69+
],
70+
[
71+
140.1031494140625,
72+
35.42374884923695
73+
],
74+
[
75+
140.1031494140625,
76+
35.77102915686019
77+
],
78+
[
79+
139.5648193359375,
80+
35.77102915686019
81+
],
82+
[
83+
139.5648193359375,
84+
35.42374884923695
85+
]
86+
]
87+
],
88+
"type": "Polygon"
89+
},
90+
"item_types": [
91+
"PSScene"
92+
],
93+
"start_time": "2023-03-17T04:08:00.0Z"
94+
}
95+
},
96+
"delivery": {
97+
"type": "destination",
98+
"parameters": {
99+
"ref": "pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX",
100+
}
101+
}
102+
}
103+
```
104+
105+
Then create the subscription, with the json above saved to a file.
106+
```sh
107+
planet subscriptions create my-subscription.json
108+
```
109+
110+
The results of the created subscription will be delivered to the destination provided.
111+
112+
To retrieve all subscriptions created with a specific destination, issue the following command:
113+
```sh
114+
planet subscriptions list --destination-ref pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX
115+
```
116+
117+
## Using destinations in Orders API
118+
After creating a destination, it can be used as the delivery location for orders. Use the destination reference in the delivery block instead of credentials.
119+
120+
The subsequent examples will use the destination ref `pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX`.
121+
```json
122+
{
123+
"name": "Order using a destination",
124+
"products": [
125+
{
126+
"item_ids": [
127+
"20220605_124027_64_242b"
128+
],
129+
"item_type": "PSScene",
130+
"product_bundle": "analytic_sr_udm2"
131+
}
132+
],
133+
"delivery": {
134+
"destination": {
135+
"ref": "pl:destinations/cp-gcs-6HRjBcW74jeH9SC4VElKqX"
136+
}
137+
}
138+
}
139+
```
140+
141+
Then create the order, with the json above saved to a file.
142+
```sh
143+
planet orders create my-order.json
144+
```
145+
146+
The results of the created order will be delivered to the destination provided.
147+
148+
To retrieve all orders created with a specific destination, issue the following command:
149+
```sh
150+
planet orders list --destination-ref pl:destinations/my-s3-destination-6HRjBcW74jeH9SC4VElKqX
151+
```

‎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/cli/cli-orders.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ The `list` command supports filtering on a variety of fields:
8383
* `--created-on`: Filter on the order creation time or an interval of creation times.
8484
* `--last-modified`: Filter on the order's last modified time or an interval of last modified times.
8585
* `--hosting`: Filter on orders containing a hosting location (e.g. SentinelHub). Accepted values are `true` or `false`.
86+
* `--destination-ref`: Filter on orders created with the provided destination reference.
8687

8788
Datetime args (`--created-on` and `--last-modified`) can either be a date-time or an interval, open or closed. Date and time expressions adhere to RFC 3339. Open intervals are expressed using double-dots.
8889
* A date-time: `2018-02-12T23:20:50Z`

0 commit comments

Comments
 (0)