Esri introduced the STAC user interface in ArcGIS Pro 3.2. This user interface(UI) allows you to make a connection to a STAC API, search for assets, and leverage them directly in ArcGIS Pro. One of the key elements when setting up the connection to a STAC API is the inclusion of ArcGIS Cloud Storage (ACS) connection files. When the datasets discovered through a STAC API are secured in their storage location, these ACS files are needed to allow ArcGIS Pro to access the datasets. Some STAC APIs (or collections referenced within them) present datasets that are stored in publicly accessible storage. These do not require ACS files to use the data in ArcGIS Pro. One example is the Earth Search STAC API of AWS Public Datasets, specifically the Sentinel-2 L2A collection.
Creating ACS files may require certain set parameters. These parameters depend on the type of datastore where the data reside. For example, the Microsoft Planetary Computer (MPC) STAC requires Azure Storage Shared Access Signature (SAS) tokens. In contrast, other STAC APIs, like Earth Search, reference some datasets on S3 that are not publicly accessible (for example, the NAIP and Landsat collections), and these connections require account credentials. The ACS connection file covers both cases and can be included when working with the STAC UI.
You will now get an overview of how to create these ACS connection files using the Create Cloud Storage Connection File geoprocessing tool. The wokflows here use examples of creating cloud storage connection files for the Landsat collection on the Microsoft Planetary Computer and on the Earth Search STAC APIs.
Creating ACS file for Microsoft Planetary Computer STAC
1. When we work with collections in the MPC STAC, we will create ACS connection files that require the following parameters.
-
- Storage Account Name: Name of the account to access this storage.
- Container Name: Name of the bucket or container.
- ARC_TOKEN_SERVICE_API: URL of the token vendor.
- ARC_TOKEN_OPTION_NAME: Type of token from the service provider.
2. We can get the account name and container information directly from the MPC site.
-
- Go to the Microsoft Planetary Computer Data Catalog. Search for and select the dataset collection you want to access. We will use the Landsat Collection 2 Level-2 as an example.
- View the Landsat Collection 2 Level-2 dataset overview page, which provides a STAC Collection link on your browser or on a JSON viewer.
- Search for two pieces of metadata: msft:storage_account and msft:container.The values of these two parameters are the Account Name and Container Name values for the Landsat collection 2 Level-2 collection.For this tutorial, use landsateuwest for Storage Account Name and landsat-c2 for Container Name.
3. Once you have the account name and container name, apply them to the ARC_TOKEN_SERVICE_API.
-
- In the request URL template, https://planetarycomputer.microsoft.com/api/sas/v1/token/{storage_account}/{container},replace {storage_account} with landsateuwest and replace {container} with landsat-c2.
- So, for the Landsat Collection 2 Level-2, the request URL is https://planetarycomputer.microsoft.com/api/sas/v1/token/landsateuwest/landsat-c2
4. We now have all the parameters that we need to create our ACS files. Open the Create Cloud Storage Connection File geoprocessing tool and set the following parameters:
-
- Connection File Location—C:\temp
- Connection File Name—landsatc2mpc.acs
- Service Provider—Azure
- Access Key ID (Account Name)—landsateuwest
- Bucket (Container) Name—landsat-c2
- Provider Options:
-
- ARC_TOKEN_OPTION_NAME — AZURE_STORAGE_SAS_TOKEN
- ARC_TOKEN_SERVICE_API — https://planetarycomputer.microsoft.com/api/sas/v1/token/landsateuwest/landsat-c2
- ARC_DEEP_CRAWL — NO
-
5. Now run the tool to create the cloud storage connection file. Once created, you can use this file when you create your connection to the Landsat collection on the MPC STAC.
Creating ACS file for Earth Search STAC
1. When we work with collections in the Earth Search STAC, we will create cloud storage connection files that require the following parameters.
-
- Access Key ID (Account Name): Name of the account that will be used to access this storage.
- Secret Access Key (Account Key): The secret access key string to authenticate the connection to cloud storage.
- Bucket (Container) Name: Name of the bucket or container.
- Region: The region string for the cloud storage.
- AWS_REQUEST_PAYER: Requester Pays buckets can be accessed by setting this option to requester.
2. Find your account name and account key, which are available once you sign up with Amazon Cloud Services and get an AWS account. Contact your administrator or IT support if needed.
3. To get the bucket name and the region, visit the Registry of Open Data on AWS
4. Search for USGS Landsat and click the Details link to open the information on the USGS Landsat on AWS
5. On this page, get the following information:
-
- Resource typeS3 Bucket: Requester Pays (Indicates this is a protected bucket and that the requester (user) is required to pay for access to this bucket)
- Amazon Resource Name (ARN): arn:aws:s3:::usgs-landsat/collection02/ (This is the bucket name and folder name.)
- AWS Region: us-west-2 (This is the region where this cloud store is.)
6. Open the Create Cloud Storage Connection File geoprocessing tool and set in the following parameters.
-
- Connection file location: C:\temp
- Connection file name: EarthSearchLS.acs
- Service Provider: Amazon
- Access Key ID (Account Name): landsateuwest
- Bucket (Container) Name: usgs-landsat
- Folder: collection02
- Region: us-west-2
- Provider Options:
- AWS_REQUEST_PAYER: requester
- ARC_DEEP_CRAWL: NO
7. Now run the tool to create the cloud storage connection file. Once created, you can use this file when you create your connection to the Landsat collection on the Earth Search STAC.
The use of ACS connection files is not limited to Azure and AWS. ArcGIS supports connections to other commercial cloud storage including Google Cloud Platform, Alibaba, WebHDFS, MinIO, Ozone, and Azure Data Lake. While this article focused on pairing ACS connection files with the ArcGIS STAC API connections, ACS connection files can be used directly to read and write data from ArcGIS Pro and Python Notebooks. Geoprocessing tools that can be used with ACS connection fines include Add Rasters to Mosaic Dataset, Copy Raster, and Transfer Files. Or you can access data in the Catalog pane by adding a folder connection to the ACS files folder and drag data to a map or scene.
About the authors
Rohan Ganapathy
Article Discussion: