Merge pull request #1095 from planetlabs/cp/hosting-create-config

add "create configuration" support for SH hosting in orders and subs

Author: charcey

docs/cli/cli-orders.md

@@ -236,11 +236,22 @@ planet orders request \
     --name 'My First Order' \
     20220605_124027_64_242b \
     --hosting sentinel_hub \
-    --collection_id ba8f7274-aacc-425e-8a38-e21517bfbeff
+    --collection-id ba8f7274-aacc-425e-8a38-e21517bfbeff
+```
+
+```
+planet orders request \
+    --item-type PSScene \
+    --bundle analytic_sr_udm2 \
+    --name 'My First Order' \
+    20220605_124027_64_242b \
+    --hosting sentinel_hub \
+    --create-configuration
 ```
 
 - The --hosting option is optional and currently supports sentinel_hub as its only value.
-- The --collection_id is also optional. If you decide to use this, ensure that the order request and the collection have matching bands. If you're unsure, allow the system to create a new collection for you by omitting the --collection_id option. This will ensure the newly set-up collection is configured correctly, and you can subsequently add items to this collection as needed.
+- The --collection-id is also optional. If you decide to use this, ensure that the order request and the collection have matching bands. If you're unsure, allow the system to create a new collection for you by omitting the --collection-id option. This will ensure the newly set-up collection is configured correctly, and you can subsequently add items to this collection as needed.
+- The --create-configuration option will create a new [layer configuration](https://apps.sentinel-hub.com/dashboard/#/configurations) in Sentinel Hub on your behalf. This option cannot be used with --collection-id.
 
 For more information on Sentinel Hub hosting, see the [Orders API documentation](https://developers.planet.com/apis/orders/delivery/#delivery-to-sentinel-hub-collection) and the [Linking Planet User to Sentinel Hub User
 ](https://support.planet.com/hc/en-us/articles/16550358397469-Linking-Planet-User-to-Sentinel-Hub-User) support post.
@@ -307,12 +318,18 @@ if you run that command again it will create a second order).
 
 #### Sentinel Hub Hosting
 
-For convenience, `planet orders create` accepts the same `--hosting` and `--collection_id` options that [`planet orders request`](#sentinel-hub-hosting) does.
+For convenience, `planet orders create` accepts the same `--hosting`, `--collection-id`, and `--create-configuration` options that [`planet orders request`](#sentinel-hub-hosting) does.
+
+```sh
+planet orders create request-1.json \
+    --hosting sentinel_hub \
+    --collection-id ba8f7274-aacc-425e-8a38-e21517bfbeff
+```
 
 ```sh
 planet orders create request-1.json \
     --hosting sentinel_hub \
-    --collection_id ba8f7274-aacc-425e-8a38-e21517bfbeff
+    --create-configuration
 ```
 
 ### Create Request and Order in One Call

docs/cli/cli-subscriptions.md

@@ -538,10 +538,11 @@ planet subscriptions request \
 
 #### Sentinel Hub Hosting
 
-When creating a new subscription, you can include hosting options directly using the --hosting and --collection-id flags.
+When creating a new subscription, you can include hosting options directly using the --hosting, --collection-id, and --create-configuration flags.
 
 - The --hosting option is optional and currently supports sentinel_hub as its only value.
-- The --collection_id is also optional. If you decide to use this, ensure that the subscription request and the collection have matching bands. If you're unsure, allow the system to create a new collection for you by omitting the --collection_id option. This will ensure the newly set-up collection is configured correctly, and you can subsequently add items to this collection as needed.
+- The --collection-id is also optional. If you decide to use this, ensure that the subscription request and the collection have matching bands. If you're unsure, allow the system to create a new collection for you by omitting the --collection-id option. This will ensure the newly set-up collection is configured correctly, and you can subsequently add items to this collection as needed.
+- The --create_configuration option will create a new [layer configuration](https://apps.sentinel-hub.com/dashboard/#/configurations) in Sentinel Hub on your behalf. This option cannot be used with --collection-id.
 - You may also input --hosting as a JSON file. The file should be formatted:
 
 ```sh

planet/cli/orders.py

@@ -268,6 +268,12 @@ async def download(ctx, order_id, overwrite, directory, checksum):
               default=None,
               help='Collection ID for Sentinel Hub hosting. '
               'If omitted, a new collection will be created.')
+@click.option(
+    '--create-configuration',
+    is_flag=True,
+    default=False,
+    help='Automatically create a layer configuration for your collection. '
+    'If omitted, no configuration will be created.')
 @pretty
 async def create(ctx, request, pretty, **kwargs):
     """Create an order.
@@ -278,17 +284,21 @@ async def create(ctx, request, pretty, **kwargs):
     REQUEST is the full description of the order to be created. It must be JSON
     and can be specified a json string, filename, or '-' for stdin.
 
-    Other flag options are hosting and collection_id. The hosting flag
-    specifies the hosting type, and the collection_id flag specifies the
-    collection ID for Sentinel Hub. If the collection_id is omitted, a new
-    collection will be created.
+    Other flag options are hosting, collection_id, and create_configuration.
+    The hosting flag specifies the hosting type, the collection_id flag specifies the
+    collection ID for Sentinel Hub, and the create_configuration flag specifies
+    whether or not to create a layer configuration for your collection. If the
+    collection_id is omitted, a new collection will be created. If the
+    create_configuration flag is omitted, no configuration will be created. The
+    collection_id flag and create_configuration flag cannot be used together.
     """
 
     hosting = kwargs.get('hosting')
     collection_id = kwargs.get('collection_id')
+    create_configuration = bool(kwargs.get('create_configuration', False))
 
     if hosting == "sentinel_hub":
-        request["hosting"] = sentinel_hub(collection_id)
+        request["hosting"] = sentinel_hub(collection_id, create_configuration)
 
     async with orders_client(ctx) as cl:
         order = await cl.create_order(request)
@@ -360,9 +370,14 @@ async def create(ctx, request, pretty, **kwargs):
               type=click.Choice(['sentinel_hub']),
               help='Hosting for data delivery. '
               'Currently, only "sentinel_hub" is supported.')
-@click.option('--collection_id',
+@click.option('--collection-id',
               help='Collection ID for Sentinel Hub hosting. '
               'If omitted, a new collection will be created.')
+@click.option(
+    '--create-configuration',
+    is_flag=True,
+    help='Automatically create a layer configuration for your collection. '
+    'If omitted, no configuration will be created.')
 @pretty
 async def request(ctx,
                   item_type,
@@ -379,6 +394,7 @@ async def request(ctx,
                   stac,
                   hosting,
                   collection_id,
+                  create_configuration,
                   pretty):
     """Generate an order request.
 
@@ -416,13 +432,15 @@ async def request(ctx,
     else:
         stac_json = {}
 
-    request = planet.order_request.build_request(name,
-                                                 products=[product],
-                                                 delivery=delivery,
-                                                 notifications=notifications,
-                                                 tools=tools,
-                                                 stac=stac_json,
-                                                 hosting=hosting,
-                                                 collection_id=collection_id)
+    request = planet.order_request.build_request(
+        name,
+        products=[product],
+        delivery=delivery,
+        notifications=notifications,
+        tools=tools,
+        stac=stac_json,
+        hosting=hosting,
+        collection_id=collection_id,
+        create_configuration=create_configuration)
 
     echo_json(request, pretty)

planet/cli/subscriptions.py

@@ -165,6 +165,11 @@ async def list_subscriptions_cmd(ctx,
               default=None,
               help='Collection ID for Sentinel Hub hosting. '
               'If omitted, a new collection will be created.')
+@click.option(
+    '--create-configuration',
+    is_flag=True,
+    help='Automatically create a layer configuration for your collection. '
+    'If omitted, no configuration will be created.')
 @pretty
 @click.pass_context
 @translate_exceptions
@@ -178,17 +183,21 @@ async def create_subscription_cmd(ctx, request, pretty, **kwargs):
     REQUEST is the full description of the subscription to be created. It must
     be JSON and can be specified a json string, filename, or '-' for stdin.
 
-    Other flag options are hosting and collection_id. The hosting flag
-    specifies the hosting type, and the collection_id flag specifies the
-    collection ID for Sentinel Hub. If the collection_id is omitted, a new
-    collection will be created.
+    Other flag options are hosting, collection_id, and create_configuration.
+    The hosting flag specifies the hosting type, the collection_id flag specifies the
+    collection ID for Sentinel Hub, and the create_configuration flag specifies
+    whether or not to create a layer configuration for your collection. If the
+    collection_id is omitted, a new collection will be created. If the
+    create_configuration flag is omitted, no configuration will be created. The
+    collection_id flag and create_configuration flag cannot be used together.
     """
 
     hosting = kwargs.get("hosting", None)
     collection_id = kwargs.get("collection_id", None)
+    create_configuration = kwargs.get('create_configuration', False)
 
     if hosting == "sentinel_hub":
-        hosting_info = sentinel_hub(collection_id)
+        hosting_info = sentinel_hub(collection_id, create_configuration)
         request["hosting"] = hosting_info
 
     async with subscriptions_client(ctx) as client:
@@ -366,6 +375,12 @@ async def list_subscription_results_cmd(ctx,
               default=None,
               help='Collection ID for Sentinel Hub hosting. '
               'If omitted, a new collection will be created.')
+@click.option(
+    '--create-configuration',
+    is_flag=True,
+    default=False,
+    help='Automatically create a layer configuration for your collection. '
+    'If omitted, no configuration will be created.')
 @pretty
 def request(name,
             source,
@@ -374,6 +389,7 @@ def request(name,
             tools,
             hosting,
             collection_id,
+            create_configuration,
             clip_to_source,
             pretty):
     """Generate a subscriptions request.
@@ -384,14 +400,16 @@ def request(name,
     default behavior.
     """
 
-    res = subscription_request.build_request(name,
-                                             source,
-                                             delivery,
-                                             notifications=notifications,
-                                             tools=tools,
-                                             hosting=hosting,
-                                             collection_id=collection_id,
-                                             clip_to_source=clip_to_source)
+    res = subscription_request.build_request(
+        name,
+        source,
+        delivery,
+        notifications=notifications,
+        tools=tools,
+        hosting=hosting,
+        collection_id=collection_id,
+        create_configuration=create_configuration,
+        clip_to_source=clip_to_source)
     echo_json(res, pretty)
 
 

planet/order_request.py

@@ -32,7 +32,8 @@ def build_request(name: str,
                   tools: Optional[List[dict]] = None,
                   stac: Optional[dict] = None,
                   hosting: Optional[str] = None,
-                  collection_id: Optional[str] = None) -> dict:
+                  collection_id: Optional[str] = None,
+                  create_configuration: Optional[bool] = False) -> dict:
     """Prepare an order request.
 
     ```python
@@ -70,6 +71,7 @@ def build_request(name: str,
         stac: Include STAC metadata.
         hosting: A hosting destination (e.g. Sentinel Hub).
         collection_id: A Sentinel Hub collection ID.
+        create_configuration: Automatically create a layer configuration for your collection.
 
     Raises:
         planet.specs.SpecificationException: If order_type is not a valid
@@ -97,7 +99,7 @@ def build_request(name: str,
         details['metadata'] = stac
 
     if hosting == 'sentinel_hub':
-        details['hosting'] = sentinel_hub(collection_id)
+        details['hosting'] = sentinel_hub(collection_id, create_configuration)
 
     return details
 
@@ -598,9 +600,12 @@ def band_math_tool(b1: str,
     return _tool('bandmath', parameters)
 
 
-def sentinel_hub(collection_id: Optional[str] = None) -> dict:
+def sentinel_hub(collection_id: Optional[str] = None,
+                 create_configuration: Optional[bool] = False) -> dict:
     """Specify a Sentinel Hub hosting destination."""
-    params = {}
+    params: Dict[str, Union[str, bool]] = {}
     if collection_id:
         params['collection_id'] = collection_id
+    if create_configuration:
+        params['create_configuration'] = create_configuration
     return {'sentinel_hub': params}

planet/subscription_request.py

@@ -54,6 +54,7 @@ def build_request(name: str,
                   tools: Optional[List[Mapping]] = None,
                   hosting: Optional[Union[Mapping, str]] = None,
                   collection_id: Optional[str] = None,
+                  create_configuration: Optional[bool] = False,
                   clip_to_source: Optional[bool] = False) -> dict:
     """Construct a Subscriptions API request.
 
@@ -68,6 +69,8 @@ def build_request(name: str,
         tools: Tools to apply to the products. The order of operation
             is determined by the service.
         hosting: A hosting destination e.g. Sentinel Hub.
+        collection_id: A Sentinel Hub collection ID.
+        create_configuration: Automatically create a layer configuration for your collection.
         clip_to_source: whether to clip to the source geometry or not
             (the default). If True a clip configuration will be added to
             the list of requested tools unless an existing clip tool
@@ -155,6 +158,9 @@ def build_request(name: str,
         }
         if collection_id:
             hosting_info["parameters"]["collection_id"] = collection_id
+        if create_configuration:
+            hosting_info["parameters"][
+                "create_configuration"] = create_configuration
         details['hosting'] = hosting_info
     elif isinstance(hosting, dict):
         details['hosting'] = hosting
@@ -769,18 +775,24 @@ def _hosting(type: str, parameters: dict) -> dict:
     return {"type": type, "parameters": parameters}
 
 
-def sentinel_hub(collection_id: Optional[str]) -> dict:
+def sentinel_hub(collection_id: Optional[str],
+                 create_configuration: Optional[bool] = False) -> dict:
     """Specify a Sentinel Hub hosting destination.
 
     Requires the user to have a Sentinel Hub account linked with their Planet
-    account.  Subscriptions API will create a new collection to deliver data to
-    if collection_id is omitted from the request.
+    account. Subscriptions API will create a new collection to deliver data to
+    if collection_id is omitted from the request. Will also create a new layer
+    configuration for the collection if create_configuration is True.
+    collection_id and create_configuration are mutually exclusive in the API.
 
     Parameters:
         collection_id: Sentinel Hub collection
+        create_configuration: Automatically create a layer configuration for your collection.
     """
 
-    parameters = {}
+    parameters: Dict[str, Union[str, bool]] = {}
     if collection_id:
         parameters['collection_id'] = collection_id
+    if create_configuration:
+        parameters['create_configuration'] = create_configuration
     return _hosting("sentinel_hub", parameters)