Developer Sandbox
api.canopy.prod.umbra-sandbox.space
The Canopy developer sandbox offers API users a convenient platform to develop integrations with increased rate limits, without generating billable Collects on the Umbra platform. By default, the developer sandbox is enabled for all accounts.
This dedicated sandbox environment simulates real data for all Canopy API endpoints, maintaining a clear separation from the live environment. Generally, fields such as satelliteID
will contain realistic values.
Sandbox Data Separation
The live and sandbox environments are entirely isolated from one another. Objects created in either environment can only be queried using an Access Token valid for the same environment.
Using the Sandbox
The Sandbox API is accessible at api.canopy.prod.umbra-sandbox.space
. To query the Sandbox instead of the live environment, replace api.canopy.umbra.space
in your API queries with api.canopy.prod.umbra-sandbox.space
.
In addition, you'll need a different Access Token. To retrieve your temporary Sandbox Access Token from the Canopy app, go to https://canopy.umbra.space/account, enable the "Test Mode" toggle in the app header, and copy the Access Token displayed while the "Test Mode" toggle is active.
Once you have an Access Token, you can follow the Task Lifecycle Tutorial to try creating a Task in the Sandbox.
Task Lifecycle
For live Tasks and Collects, the status
field provides users information about the current state of the Task and Collect. When Tasks are created in the live system, the status transitions as major lifecycle events take place, such as scheduling, collection, downlinking, processing, and delivery.
In the developer sandbox, these status changes and transitions are mocked as follows:
- After a new Task is created, the status transitions every few seconds from
RECEIVED
through toSCHEDULED
. - Once the Task is
SCHEDULED
the associated Collect(s) are created with statusSCHEDULED
. - Within a minute after the
Task.windowEndAt
passes, the status for each Collect associated with the Task will rapidly transition every few seconds fromSCHEDULED
through toPROCESSED
.- As in the live system, as the underlying Collect status transitions, the associated Task status will transition accordingly based on the Task
imagingMode
.
- As in the live system, as the underlying Collect status transitions, the associated Task status will transition accordingly based on the Task
- As each
Collect
is markedPROCESSED
, any normal post-processing operations will occur, including delivery of fake data associated with the Collect. - Just like in the live system, Collects and their associated Tasks are marked
DELIVERED
when:- If the Task has a DeliveryConfig set, when the copy operation associated with that DeliveryConfig is complete.
- If the Task has no DeliveryConfig, when the data is available for download in Canopy.
Feasibilities
There are some functional differences between Feasibilities and Opportunities in the Sandbox vs the live system.
- Opportunities returned for a given Feasibility request are static, and do not necessarily represent the parameters sent on the Feasibility request. For example, the
windowStartAt
andwindowEndAt
on an Opportunity may not match the same window in the parent Feasibility's SpotlightConstraints. - Feasibility results are generally returned much more quickly (<1s) than in the live system. Ensure your application treats retrieving Opportunities for Feasibility as an asynchronous operation.
Data Delivery
All DeliveryConfig operations are supported in the sandbox. Users can create DeliveryConfigs and add them to their Tasks, and fake data will be delivered just like in the live environment.
S3_UMBRA_ROLE Configuration
To support testing data delivery via this DeliveryConfig type, you'll need to allow additional role(s) to your Bucket Policy as described here: https://docs.canopy.umbra.space/docs/delivery-configs#apply-s3-bucket-policy
- Sandbox ARN, AWS commercial:
arn:aws:iam::922714215458:role/prod-prod-sbx-s3-external-delivery
- Sandbox ARN, AWS GovCloud:
arn:aws-us-gov:iam::537355544329:role/prod-gov-prod-sbx-sar-data-delivery-cross-account-role
Don't forget to also include the KMS Key Policy for these roles if your Bucket is encrypted.
Triggering Failures
Sandbox Tasks support triggering specific failures by including a specific string anywhere in the submitted taskName
field when POSTing new Tasks.
Failure | String for taskName | Description |
---|---|---|
QA Failure | umbra:delivery:qa:failure | Collect behaves as if Umbra's automated QA failed. See Automated QA for additional information. |
Example
This POST body for Create Task will trigger the "QA Failure" failure mode as described in the table above:
{
{
"imagingMode": "SPOTLIGHT",
"taskName": "Test umbra:delivery:qa:failure",
"windowStartAt": "2023-12-25T18:00:00+00:00",
"windowEndAt": "2023-12-26T00:00:00+00:00",
"spotlightConstraints": {
"geometry": {
"type": "Point",
"coordinates": [-119.7027, 34.4221]
}
}
}
Updated 10 months ago