Criar uma conexão base Amazon S3 usando a API Flow Service

Uma conexão base representa a conexão autenticada entre uma origem e o Adobe Experience Platform.

Este tutorial guiará você pelas etapas para criar uma conexão básica para Amazon S3 (doravante denominada "S3") usando a Flow Service API.

Introdução

Este manual necessita de uma compreensão funcional dos seguintes componentes da Adobe Experience Platform:

  • Fontes: Experience Platform permite que os dados sejam assimilados de várias fontes e fornece a capacidade de estruturar, rotular e aprimorar os dados recebidos usando os serviços do Platform.
  • Sandboxes: Experience Platform fornece sandboxes virtuais que particionam uma única instância do Platform em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.

As seções a seguir fornecem informações adicionais que você precisará saber para se conectar com êxito a um armazenamento do S3 usando a API Flow Service.

Coletar credenciais necessárias

Para que Flow Service se conecte ao armazenamento S3, você deve fornecer valores para as seguintes propriedades de conexão:

Credencial
Descrição
s3AccessKey
A ID da chave de acesso do seu bucket S3.
s3SecretKey
A ID da chave secreta para o bucket S3.
serviceUrl
(Opcional) O ponto de extremidade S3 personalizado ao qual se conectar. Este campo é necessário quando a classificação S3 é específica da região. O formato de serviceUrl é: https://s3.{REGION}.amazonaws.com/).
bucketName
O bucket S3 contém seus dados e seus metadados descritivos correspondentes. O nome do bucket do S3 deve ter entre três e 63 caracteres e deve começar e terminar com uma letra ou um número. O nome do bucket só pode ter letras minúsculas, números ou hifens (-) e não pode ser formatado como um endereço IP.
folderPath
O caminho para a pasta no seu bucket S3 onde seus dados estão armazenados. Essa credencial é necessária quando o usuário tem acesso restrito.
s3SessionToken
(Opcional) Um token temporário de curto prazo que permite fornecer acesso temporário aos recursos do S3 para usuários em ambientes não confiáveis. Consulte a S3 visão geral para obter mais informações.
connectionSpec.id
A especificação de conexão retorna as propriedades do conector de uma origem, incluindo especificações de autenticação relacionadas à criação das conexões de base e de origem. A ID da especificação de conexão para S3 é: ecadc60c-7455-4d87-84dc-2a0e293d997b.

Para obter mais informações de introdução, visite este Amazon Web Services documento.

Uso de APIs da plataforma

Para obter informações sobre como fazer chamadas para APIs da Platform com êxito, consulte o manual sobre introdução às APIs da Platform.

Criar uma conexão básica

Uma conexão base retém informações entre sua origem e a Platform, incluindo as credenciais de autenticação da origem, o estado atual da conexão e sua ID de conexão base exclusiva. A ID de conexão básica permite explorar e navegar pelos arquivos de dentro da origem e identificar os itens específicos que deseja assimilar, incluindo informações sobre os tipos de dados e formatos.

Para criar uma ID de conexão base, faça uma solicitação POST para o ponto de extremidade /connections enquanto fornece suas credenciais de autenticação S3 como parte dos parâmetros de solicitação.

Formato da API

POST /connections

Solicitação

A solicitação a seguir cria uma conexão base para S3:

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/connections' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Amazon S3 base connection",
        "description": "Amazon S3 base connection with temporary session token",
        "auth": {
            "specName": "Access Key",
            "params": {
                "s3AccessKey": "{S3_ACCESS_KEY}",
                "s3SecretKey": "{S3_SECRET_KEY}",
                "s3SessionToken": "{S3_SESSION_TOKEN}
            }
        },
        "connectionSpec": {
            "id": "ecadc60c-7455-4d87-84dc-2a0e293d997b",
            "version": "1.0"
        }
    }'
Propriedade
Descrição
auth.params.s3AccessKey
A chave de acesso associada ao seu bucket S3.
auth.params.s3SecretKey
Sua chave secreta associada ao seu bucket S3.
auth.params.s3SessionToken
(Opcional) O token S3 temporário de curto prazo usado para acessar seu bucket.
connectionSpec.id
A ID da especificação de conexão S3: ecadc60c-7455-4d87-84dc-2a0e293d997b

Resposta

Uma resposta bem-sucedida retorna detalhes da conexão recém-criada, incluindo seu identificador exclusivo (id). Essa ID é necessária para explorar seu armazenamento no próximo tutorial.

{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"1700d77b-0000-0200-0000-5e3b41a10000\""
}

Próximas etapas

Seguindo este tutorial, você criou uma conexão S3 usando APIs e uma ID exclusiva foi obtida como parte do corpo da resposta. Você pode usar esta ID de conexão para explorar armazenamentos em nuvem usando a API de Serviço de Fluxo.

Apêndice

A seção a seguir fornece informações adicionais sobre o uso da origem S3.

Atualizar o token de sessão S3

O s3SessionToken é temporário e deve ser atualizado quando expirar. Você pode atualizar o token de sessão associado à sua conexão básica fazendo uma solicitação PATCH para a API Flow Service. Consulte a S3 visão geral para obter mais informações sobre credenciais de segurança temporárias para S3.

IMPORTANT
O cabeçalho If-Match é necessário ao fazer uma solicitação PATCH. O valor desse cabeçalho é a tag exclusiva da conexão que você deseja atualizar.

Formato da API

PATCH /connections

Solicitação

A solicitação a seguir cria uma conexão base para S3:

curl -X PATCH \
    'https://platform.adobe.io/data/foundation/flowservice/connections/4cb0c374-d3bb-4557-b139-5712880adc55' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'If-Match: "1700d77b-0000-0200-0000-5e3b41a10000"'
    -d '[
        {
            "op": "replace",
            "path": "/auth/params/s3SessionToken",
            "value": "{SESSION_TOKEN}"
        }
    ]'
Parâmetro
Descrição
op
A chamada de operação usada para definir a ação necessária para atualizar a conexão. As operações incluem: add, replace e remove.
path
O caminho do parâmetro a ser atualizado.
value
O novo valor com o qual você deseja atualizar seu parâmetro.

Resposta

Uma resposta bem-sucedida retorna a ID de conexão básica e uma tag atualizada. Você pode verificar a atualização fazendo uma solicitação GET para a API Flow Service e, ao mesmo tempo, fornecendo a ID da conexão.

{
    "id": "4cb0c374-d3bb-4557-b139-5712880adc55",
    "etag": "\"3600e378-0000-0200-0000-5f40212f0000\""
}
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089