Compartilhar via

Configurar uma fonte de ingestão para o Microsoft Planetary Computer Pro usando tokens SAS

O carregamento de novos dados no recurso Microsoft Planetary Computer Pro GeoCatalog é chamado de ingestão. Um GeoCatalog precisa de permissões ou fontes de ingestão para acessar dados armazenados externamente no recurso GeoCatalog.   Neste guia, você aprenderá a:

  • Criar uma fonte de ingestão por meio do portal do Azure
  • Criar uma fonte de ingestão por meio da API do Microsoft Planetary Computer Pro usando o SDK do Python do Azure

Pré-requisitos

Identidade gerenciada versus tokens SAS

As identidades gerenciadas fornecem uma identidade gerenciada automaticamente na ID do Microsoft Entra para que os aplicativos usem ao se conectar a recursos que dão suporte à autenticação do Microsoft Entra.

As SAS (Assinaturas de Acesso Compartilhado) criam credenciais criptográficas para acesso a um recurso como o Armazenamento de Blobs do Azure.

As identidades gerenciadas são um mecanismo automatizado mais seguro para estabelecer o acesso persistente a uma conta de armazenamento e são a abordagem recomendada para fornecer acesso seguro ao Armazenamento de Blobs do Azure para ingestão de dados.

As identidades gerenciadas funcionam apenas em um único locatário do Microsoft Entra, portanto, a abordagem de Token SAS é útil ao mover dados do armazenamento que estão em uma conta de armazenamento fora do seu locatário. A ingestão de dados é específica para um Contêiner de Blobs e os tokens de SAS do recurso de armazenamento raiz não são permitidos.

Configurar uma fonte de ingestão por meio da interface do usuário

Os tokens SAS podem ser obtidos de várias maneiras; neste guia, fazemos isso usando o portal do Azure. O Gerenciador de Armazenamento do Azure também é uma abordagem alternativa orientada pela interface do usuário que funciona em um computador local. Consulte o Gerenciador de Armazenamento do Azure

No portal do Azure, localize o Recurso de Armazenamento que contém o Contêiner de Blobs do Azure com os dados que você deseja ingerir no Planetry Computer Pro. Nas configurações de recurso, selecione a configuração "Contêineres" em "Armazenamento de Dados".

Captura de tela do portal do Azure mostrando a seção Contêineres em Armazenamento de Dados para uma Conta de Armazenamento selecionada.

Selecione seu contêiner de blob e solicite um Token SAS

Selecione o contêiner específico que você deseja ingerir, neste exemplo, estamos selecionando o contêiner de "teste".

Captura de tela do portal do Azure mostrando a página de configuração de tokens de acesso compartilhado para um Contêiner de Blobs selecionado.

Selecione a configuração "Tokens de acesso compartilhado" e abra as configurações.

Captura de tela do portal do Azure mostrando a página de configuração de tokens de acesso compartilhado para um Contêiner de Blobs selecionado. A página inclui campos para definir permissões, horários de início e expiração e botões para gerar o token SAS e a URL.

Verifique se essas configurações estão configuradas corretamente:

  • Permissões = Leitura (verifique se nenhuma outra opção está selecionada)
  • A validade do Token SAS abrange o tempo necessário para ingerir dados (a melhor prática de segurança é ter esse token válido no máximo sete dias)

Depois que as configurações forem verificadas, selecione o botão "Gerar Token e URL sas ". Você verá dois elementos gerados: o Token SAS do Blob e a URL SAS do Blob. Mantenha sua guia/janela aberta, pois você precisará dessas informações para a próxima seção.

Use a URL do seu Planetary Computer Pro para navegar até a página inicial e selecionar a guia "Configurações" na barra de navegação.

Captura de tela do Portal do GeoCatalog mostrando onde o botão Configurações está localizado.

Criar sua fonte de ingestão

  • Selecione o botão Criar fonte de ingestão
  • Insira o URL do Contêiner de Blobs no campo URL do Contêiner

    • Inclua apenas a URL e não inclua a chave. O formato da URL deve ser:

      https://(Storage Resource Name).blob.core.windows.net/(Blob Container Name)

  • Recortar e colar o token SAS no campo Token de Credencial .

    • Um token SAS se parece com uma cadeia de caracteres de consulta. Inclua todo o texto começando com o ? símbolo:

      exemplo:?sv=<signed-version>&ss=<signed-services>&srt=<signed-resource-types>&sp=<signed-permissions>&se=<signed-expiry-time>&st=<signed-start-time>&spr=<signed-protocol>&sig=<signature>

  • Selecione o botão Criar

Captura de tela da página Configurações do Planetário Computer Pro mostrando uma fonte de ingestão criada com êxito. A página exibe a URL do Contêiner, o Token de Credencial e uma data de validade para a credencial.

Sua fonte de ingestão agora está configurada para dar suporte à ingestão de dados!

Se a ingestão expirar ou você precisar adicionar tokens SAS para um Contêiner de Blob diferente, repita o processo anterior.

Configurar a fonte de ingestão para tokens SAS por meio da API

As fontes de ingestão também podem ser definidas por meio da API usando o Serviço de Armazenamento do SDK do Azure e a API de Computador Planetário. Consulte a documentação da API sobre fontes de ingestão.

O bloco de código a seguir importa as bibliotecas necessárias e configura as variáveis de chave.

  • Substitua <your_container_url> pela URL do Contêiner de Blobs do Azure que contém os dados que você deseja ingerir.
  • Substitua <your_geocatalog_url> pelo URL do ponto de extremidade de recurso do Computador Planetário Pro.
  • Substitua <token_duration_in_hours> por quantas horas você deseja que o token SAS seja válido (o padrão é 168 horas, o que é 7 dias).
import requests
from azure.identity import AzureCliCredential
from datetime import datetime, timedelta, timezone
import azure.storage.blob
from urllib.parse import urlparse

###################################

# Set Key Variables Here
## The Planetary Computer Pro App ID. Do not change.
MPCPRO_APP_ID = "https://geocatalog.spatio.azure.com"

## The API version. Do not change.
API_VERSION = "2025-04-30-preview"

## Replace with the URL of the Blob Container
CONTAINER_URL = "<your_container_url>" # e.g., "https://youraccount.blob.core.windows.net/yourcontainer"

## Replace with the URL of your GeoCatalog Resource
GEOCATALOG_URL = "<your_geocatalog_url>" # e.g., "https://yourgeocatalog.randomid.region.geocatalog.spatio.azure.com/"

## Replace with the desired duration of the token in hours (default: 168 hours = 7 days)
EXPIRATION_HOURS = <token_duration_in_hours> # e.g., 7 * 24

O próximo bloco de código usa o SDK do Azure para solicitar um token SAS para o Contêiner de Blobs especificado.

# Parse the container URL
parsed_url = urlparse(CONTAINER_URL)
account_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
account_name = parsed_url.netloc.split(".")[0]
container_name = parsed_url.path.lstrip("/")

# Login to Azure using the Azure CLI
credential = azure.identity.AzureCliCredential()

# Set up Blob Service Client
with azure.storage.blob.BlobServiceClient(
        account_url=account_url,
        credential=credential,
    ) as blob_service_client:
        now = datetime.now(timezone.utc).replace(microsecond=0)
        key = blob_service_client.get_user_delegation_key(
            key_start_time=now + timedelta(hours=-1),
            key_expiry_time=now + timedelta(hours = EXPIRATION_HOURS), )

# Generate the SAS token
sas_token = azure.storage.blob.generate_container_sas(
    account_name=account_name,
    container_name=container_name,
    user_delegation_key=key,
    permission=azure.storage.blob.ContainerSasPermissions(
        read=True,
        list=True,
    ),
    start=now + timedelta(hours=-1),
    expiry=now + timedelta(hours = EXPIRATION_HOURS),)

O próximo bloco de código usa a API Do Computador Planetário Pro para postar a credencial.

# Obtain an access token
credential = AzureCliCredential()
access_token = credential.get_token(f"{MPCPRO_APP_ID}/.default")

# Payload for the POST request
payload = {
    "sourceType": "SasToken",
    "connectionInfo": {
        "containerUrl": CONTAINER_URL,
        "sasToken": sas_token,
    },
}

# STAC Collection API endpoint
endpoint = f"{GEOCATALOG_URL}/inma/ingestion-sources"

# Make the POST request
response = requests.post(
    endpoint,
    json=payload,
    headers={"Authorization": f"Bearer {access_token.token}"},
    params={"api-version": API_VERSION},
)

# Print the response
if response.status_code == 201:
    print("Ingestion source created successfully")
else:
    print(f"Failed to create ingestion: {response.text}")

Próximas etapas

Agora que você configurou a identidade gerenciada, é hora de ingerir dados.

Para ingestão de item único:

Adicionando um item a uma coleção STAC

Para ingestão em massa:

Ingerir dados no GeoCatalog com a API de Ingestão em Massa

Conteúdo relacionado