Skip to content

Commit aa17791

Browse files
charceyasonnenscheinCopilot
authored
Add destinations api client (#1175)
* make source type truly optional for planetary_variable_source * python sync and async cli with tests * add cli, new md * more cli tutorial, pass in ref in orders cli on list * back out accidently committed unrelated changes * type edit on cli md * fix url * linting * lint and add ref to sync list * Apply suggestions from code review Co-authored-by: Adrian Sonnenschein <[email protected]> Co-authored-by: Copilot <[email protected]> * Apply suggestions from code review Co-authored-by: Adrian Sonnenschein <[email protected]> Co-authored-by: Copilot <[email protected]> * update cli args to options, update examples * add cli tests --------- Co-authored-by: Adrian Sonnenschein <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 52b6760 commit aa17791

17 files changed

+1260
-11
lines changed

‎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-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`

‎docs/cli/cli-subscriptions.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -130,7 +130,7 @@ outputs the JSON for your first 100 subscriptions. If you'd like more you can se
130130
parameter higher, or you can set it to 0 and there will be no limit. By default the `list` command will request Subscriptions API with a page size of 500 subscriptions, and can be set lower or higher with the `--page-size` parameter.
131131

132132
You can get nicer formatting with `--pretty` or pipe it into `jq`, just like the other Planet
133-
CLI’s.
133+
CLIs.
134134

135135
#### Filtering
136136

@@ -139,11 +139,12 @@ The `list` command supports filtering on a variety of fields:
139139
* `--end-time`: Filter on the subscription end time or an interval of end times.
140140
* `--hosting`: Filter on subscriptions containing a hosting location (e.g. SentinelHub). Accepted values are `true` or `false`.
141141
* `--name-contains`: Filter on subscriptions with a name that contains the provided string.
142-
* `--name`: Filter on subscriptions with a specific name
142+
* `--name`: Filter on subscriptions with a specific name.
143143
* `--source-type`: Filter by the source type of the subscription. For the full list of available source types, see [Subscription Source Types](https://docs.planet.com/develop/apis/subscriptions/sources/#catalog-source-type). Multiple source type args are allowed.
144144
* `--start-time`: Filter on the subscription start time or an interval of start times.
145145
* `--status`: Filter on the status of the subscription. Status options include `running`, `cancelled`, `preparing`, `pending`, `completed`, `suspended`, and `failed`. Multiple status args are allowed.
146146
* `--updated`: Filter on the subscription update time or an interval of updated times.
147+
* `--destination-ref`: Filter on subscriptions created with the provided destination reference.
147148

148149
Datetime args (`--created`, `end-time`, `--start-time`, and `--updated`) 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.
149150
* A date-time: `2018-02-12T23:20:50Z`

‎planet/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
from . import data_filter, order_request, reporting, subscription_request
1717
from .__version__ import __version__ # NOQA
1818
from .auth import Auth
19-
from .clients import DataClient, FeaturesClient, OrdersClient, SubscriptionsClient # NOQA
19+
from .clients import DataClient, DestinationsClient, FeaturesClient, OrdersClient, SubscriptionsClient # NOQA
2020
from .io import collect
2121
from .sync import Planet
2222

@@ -25,6 +25,7 @@
2525
'collect',
2626
'DataClient',
2727
'data_filter',
28+
'DestinationsClient',
2829
'FeaturesClient',
2930
'OrdersClient',
3031
'order_request',

‎planet/cli/cli.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020

2121
import planet
2222

23-
from . import auth, collect, data, orders, subscriptions, features
23+
from . import auth, collect, data, destinations, orders, subscriptions, features
2424

2525
LOGGER = logging.getLogger(__name__)
2626

@@ -78,4 +78,5 @@ def _configure_logging(verbosity):
7878
main.add_command(orders.orders) # type: ignore
7979
main.add_command(subscriptions.subscriptions) # type: ignore
8080
main.add_command(collect.collect) # type: ignore
81-
main.add_command(features.features)
81+
main.add_command(features.features) # type: ignore
82+
main.add_command(destinations.destinations) # type: ignore

0 commit comments

Comments
 (0)