DocumentatieExperience PlatformGids voor Source Connectors

Verbind Data Landing Zone met Adobe Experience Platform gebruikend de Dienst API van de Stroom

Last update: Wed Oct 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Onderwerpen:

Gemaakt voor:

  • Ontwikkelaar
IMPORTANT
Deze pagina is specifiek voor de Data Landing Zone bron schakelaar in Experience Platform. Voor informatie bij het verbinden met de Data Landing Zone bestemmings schakelaar, verwijs naar de Data Landing Zone pagina van de bestemmingsdocumentatie.

Data Landing Zone is een veilige, op de cloud gebaseerde opslagvoorziening voor bestanden die naar Adobe Experience Platform kunnen worden overgebracht. Gegevens worden automatisch na zeven dagen uit de Data Landing Zone verwijderd.

Dit leerprogramma begeleidt u door de stappen op hoe te om a Data Landing Zone bronverbinding tot stand te brengen gebruikend Flow Service API. Deze zelfstudie bevat ook instructies voor het ophalen van Data Landing Zone en het weergeven en vernieuwen van uw referenties.

Aan de slag

Deze handleiding vereist een goed begrip van de volgende onderdelen van het Experience Platform:

  • Bronnen: Experience Platform staat gegevens toe om van diverse bronnen worden opgenomen terwijl het voorzien van u van de capaciteit om, inkomende gegevens te structureren te etiketteren en te verbeteren gebruikend de diensten van het Platform.
  • Sandboxes: Experience Platform verstrekt virtuele zandbakken die één enkele instantie van het Platform in afzonderlijke virtuele milieu's verdelen helpen digitale ervaringstoepassingen ontwikkelen en ontwikkelen.

De volgende secties bevatten aanvullende informatie die u moet weten om een Data Landing Zone -bronverbinding met de Flow Service API te kunnen maken.

Dit leerprogramma vereist u ook om de gids te lezen over begonnen wordt met Platform APIsom te leren hoe te aan Platform APIs voor authentiek te verklaren en de voorbeeldvraag te interpreteren die in de documentatie wordt verstrekt.

Een bruikbare landingszone ophalen

De eerste stap bij het gebruik van API's voor toegang tot Data Landing Zone is het aanvragen van een GET voor het /landingzone eindpunt van de Connectors API terwijl het opgeven van type=user_drop_zone als onderdeel van de aanvraagheader.

API formaat

GET /data/foundation/connectors/landingzone?type=user_drop_zone
Kopteksten
Beschrijving
user_drop_zone
Met het type user_drop_zone kan de API een landingszone-container onderscheiden van de andere typen containers die voor u beschikbaar zijn.

Verzoek

Met het volgende verzoek wordt een bestaande landingszone opgehaald.

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
  -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'

Reactie

De volgende reactie retourneert informatie over een landingszone, inclusief de corresponderende containerName en containerTTL .

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}
Eigenschap
Beschrijving
containerName
De naam van de landingszone die u hebt opgehaald.
containerTTL
De vervaltijd (in dagen) die op uw gegevens binnen de landingszone wordt toegepast. Alle gegevens binnen een bepaalde landingszone worden na zeven dagen verwijderd.

Data Landing Zone gebruikersgegevens ophalen

Als u referenties voor een Data Landing Zone wilt ophalen, vraagt u een GET aan bij het /credentials -eindpunt van de Connectors API.

API formaat

GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone

Verzoek

In het volgende aanvraagvoorbeeld worden de gegevens voor een bestaande landingszone opgehaald.

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
  -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' \

Reactie

De volgende reactie retourneert de referentie-informatie voor de landingszone van uw gegevens, inclusief de huidige SASToken , SASUri , storageAccountName en vervaldatum.

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "expiryDate": "2024-01-06"
}
Eigenschap
Beschrijving
containerName
De naam van uw landingszone.
SASToken
Het token voor gedeelde toegangshandtekeningen voor uw landingszone. Deze tekenreeks bevat alle informatie die nodig is om een aanvraag te autoriseren.
SASUri
De URI van de gedeelde toegangshandtekening voor uw landingszone. Deze tekenreeks is een combinatie van de URI naar de landingszone waarvoor u geauthenticeerd wordt en de bijbehorende SAS-token,
expiryDate
De datum waarop uw SAS-token verloopt. U moet uw token vernieuwen vóór de vervaldatum om het te kunnen blijven gebruiken in uw toepassing voor het uploaden van gegevens naar de landingszone van gegevens. Als u niet manueel uw teken vóór de verklaarde vervaldatum vernieuwt, dan zal het automatisch verfrissen en een nieuw teken verstrekken wanneer de geloofsbrieven van de GET worden uitgevoerd.

De vereiste velden ophalen met behulp van API's

Nadat u uw token hebt gegenereerd, kunt u de vereiste velden programmatisch ophalen aan de hand van de onderstaande aanvraagvoorbeelden:

Python
code language-py 
import requests

# API endpoint
url = "https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone"

headers = {
    "Authorization": "{TOKEN}",
    "Content-Type": "application/json",
    "x-gw-ims-org-id": "{ORG_ID}",
    "x-api-key": "{API_KEY}"
}

# Send GET request to the API
response = requests.get(url, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    # Parse the response as JSON (if applicable)
    data = response.json()

    # Print or work with the fetched data
    print(" Sas Token:", data['SASToken'])
    print(" Container Name:",  data['containerName'])
    print("\n")

else:
    # Print an error message if the request failed
    print(f"Failed to fetch data. Status code: {response.status_code}")
    print(f"Response: {response.text}")
Java
code language-java 
package org.example;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;

import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) {

        ObjectMapper objectMapper = new ObjectMapper();

        try {

            DefaultHttpClient httpClient = new DefaultHttpClient();
            HttpGet getRequest = new HttpGet(
                "https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone");
            getRequest.addHeader("accept", "application/json");
            getRequest.addHeader("Authorization","<TOKEN>");
            getRequest.addHeader("Content-Type", "application/json");
            getRequest.addHeader("x-gw-ims-org-id", "<ORG_ID>");
            getRequest.addHeader("x-api-key", "<API_KEY>");

            HttpResponse response = httpClient.execute(getRequest);

            if (response.getStatusLine().getStatusCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                    + response.getStatusLine().getStatusCode());
            }

            final JsonNode jsonResponse = objectMapper.readTree(response.getEntity().getContent());

            System.out.println("\nOutput from API Response .... \n");
            System.out.printf("ContainerName: %s%n", jsonResponse.at("/containerName").textValue());
            System.out.printf("SASToken: %s%n", jsonResponse.at("/SASToken").textValue());

            httpClient.getConnectionManager().shutdown();

        } catch (ClientProtocolException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

Data Landing Zone gebruikersgegevens bijwerken

U kunt uw SASToken bijwerken door een aanvraag voor een POST in te dienen bij het /credentials eindpunt van de Connectors API.

API formaat

POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
Kopteksten
Beschrijving
user_drop_zone
Met het type user_drop_zone kan de API een landingszone-container onderscheiden van de andere typen containers die voor u beschikbaar zijn.
refresh
Met de handeling refresh kunt u de gegevens van de landingszone opnieuw instellen en automatisch een nieuwe SASToken genereren.

Verzoek

Met het volgende verzoek worden de gegevens van uw landingszone bijgewerkt.

curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
  -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' \

Reactie

In het volgende antwoord worden bijgewerkte waarden voor de SASToken en SASUri geretourneerd.

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "expiryDate": "2024-01-06"
}

Bestandsstructuur en inhoud van landingszones verkennen

U kunt de bestandsstructuur en de inhoud van de landingszone verkennen door een aanvraag voor een GET in te dienen bij het eindpunt connectionSpecs van de Flow Service API.

API formaat

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
Parameter
Beschrijving
{CONNECTION_SPEC_ID}
De verbindingsspecificatie-id die overeenkomt met Data Landing Zone . Deze vaste id is: 26f526f2-58f4-4712-961d-e41bf1ccc0e8 .

Verzoek

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
    -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}'

Reactie

Een succesvol antwoord retourneert een array met bestanden en mappen die in de gevraagde map zijn gevonden. Let op de eigenschap path van het bestand dat u wilt uploaden, aangezien u dit in de volgende stap moet opgeven om de structuur te controleren.

[
    {
        "type": "file",
        "name": "account.csv",
        "path": "dlz-user-container/account.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "file",
        "name": "data8.csv",
        "path": "dlz-user-container/data8.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "folder",
        "name": "userdata1",
        "path": "dlz-user-container/userdata1/",
        "canPreview": false,
        "canFetchSchema": false
    }
]

Bestandsstructuur en inhoud van landingszone voorvertonen

Om de structuur van een dossier in uw landende streek te inspecteren, voer een verzoek van de GET uit terwijl het verstrekken van de weg van het dossier en type als vraagparameter.

API formaat

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
Parameter
Beschrijving
Voorbeeld
{CONNECTION_SPEC_ID}
De verbindingsspecificatie-id die overeenkomt met Data Landing Zone . Deze vaste id is: 26f526f2-58f4-4712-961d-e41bf1ccc0e8 .
{OBJECT_TYPE}
Het type object waartoe u toegang wilt hebben.
file
{OBJECT}
Het pad en de naam van het object waartoe u toegang wilt hebben.
dlz-user-container/data8.csv
{FILE_TYPE}
Het type bestand.
  • delimited
  • json
  • parquet
{PREVIEW}
Een Booleaanse waarde die definieert of de voorvertoning van het bestand wordt ondersteund.

  • true

  • false

Verzoek

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
    -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}'

Reactie

Een succesvol antwoord geeft de structuur van het gevraagde bestand, inclusief bestandsnamen en gegevenstypen.

{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "Id",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "FirstName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "LastName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Email",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Phone",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "Email": "rsmith@abc.com",
            "FirstName": "Richard",
            "Phone": "111111111",
            "Id": "12345",
            "LastName": "Smith"
        },
        {
            "Email": "morgan@bac.com",
            "FirstName": "Morgan",
            "Phone": "22222222222",
            "Id": "67890",
            "LastName": "Hart"
        }
    ]
}

Gebruik determineProperties om automatisch informatie over de bestandseigenschappen van een Data Landing Zone te detecteren

U kunt de parameter determineProperties gebruiken om eigenschapinformatie van de dossierinhoud van uw Data Landing Zone automatisch te ontdekken wanneer het maken van een vraag van de GET om de inhoud en de structuur van uw bron te onderzoeken.

determineProperties gebruikt hoofdletters/kleine letters

In de volgende tabel worden verschillende scenario's beschreven die u kunt tegenkomen wanneer u de query-parameter determineProperties gebruikt of handmatig informatie over het bestand opgeeft.

determineProperties
queryParams
Antwoord
Waar
N.v.t.
Als determineProperties wordt verstrekt als vraagparameter, dan komt de dossiereigenschappen opsporing voor en de reactie keert een nieuwe properties sleutel terug die informatie over dossiertype, compressietype, en kolomscheidingsteken omvat.
N.v.t.
Waar
Als de waarden voor bestandstype, compressietype en kolomscheidingsteken handmatig worden opgegeven als onderdeel van queryParams , worden deze gebruikt om het schema te genereren en worden dezelfde eigenschappen geretourneerd als onderdeel van het antwoord.
Waar
Waar
Als beide opties gelijktijdig worden uitgevoerd, wordt een fout geretourneerd.
N.v.t.
N.v.t.
Als geen van beide opties wordt opgegeven, wordt een fout geretourneerd omdat er geen manier is om eigenschappen voor de reactie op te halen.

API formaat

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
Parameter
Beschrijving
Voorbeeld
determineProperties
Met deze queryparameter kan de Flow Service -API informatie detecteren over de eigenschappen van het bestand, zoals informatie over het bestandstype, het compressietype en het kolomscheidingsteken.
true

Verzoek

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
    -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}'

Reactie

Een succesvol antwoord retourneert de structuur van het bestand waarop de vraag betrekking heeft, inclusief bestandsnamen en gegevenstypen, en ook een properties -sleutel met informatie over fileType , compressionType en columnDelimiter .

klik op mij
code language-json 
{
    "properties": {
        "fileType": "delimited",
        "compressionType": "tarGzip",
        "columnDelimiter": "~"
    },
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "id",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "firstName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "lastName",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "email",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "birthday",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "birthday": "1313-0505-19731973",
            "firstName": "Yvonne",
            "lastName": "Thilda",
            "id": "100",
            "email": "Yvonne.Thilda@yopmail.com"
        },
        {
            "birthday": "1515-1212-19731973",
            "firstName": "Mary",
            "lastName": "Pillsbury",
            "id": "101",
            "email": "Mary.Pillsbury@yopmail.com"
        },
        {
            "birthday": "0505-1010-19751975",
            "firstName": "Corene",
            "lastName": "Joeann",
            "id": "102",
            "email": "Corene.Joeann@yopmail.com"
        },
        {
            "birthday": "2727-0303-19901990",
            "firstName": "Dari",
            "lastName": "Greenwald",
            "id": "103",
            "email": "Dari.Greenwald@yopmail.com"
        },
        {
            "birthday": "1717-0404-19651965",
            "firstName": "Lucy",
            "lastName": "Magdalen",
            "id": "199",
            "email": "Lucy.Magdalen@yopmail.com"
        }
    ]
}
Eigenschap
Beschrijving
properties.fileType
Het corresponderende bestandstype van het bestand waarnaar wordt gevraagd. De ondersteunde bestandstypen zijn: delimited , json en parquet .
properties.compressionType

Het corresponderende compressietype dat wordt gebruikt voor het bestand waarnaar wordt gevraagd. De ondersteunde compressietypen zijn:

  • bzip2
  • gzip
  • zipDeflate
  • tarGzip
  • tar
properties.columnDelimiter
Het corresponderende kolomscheidingsteken dat wordt gebruikt voor het bestand waarnaar wordt gevraagd. Elke waarde van één teken is een toegestaan kolomscheidingsteken. De standaardwaarde is een komma (,) .

Een bronverbinding maken

Een bronverbinding maakt en beheert de verbinding met de externe bron vanwaar gegevens worden ingevoerd. Een bronverbinding bestaat uit informatie zoals gegevensbron, gegevensformaat, en bron identiteitskaart nodig om een gegevensstroom tot stand te brengen. Een bronverbindingsinstantie is specifiek voor een huurder en organisatie.

Als u een bronverbinding wilt maken, vraagt u een POST naar het /sourceConnections -eindpunt van de Flow Service API.

API formaat

POST /sourceConnections

Verzoek

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
    -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": "Data Landing Zone source connection",
        "data": {
            "format": "delimited"
        },
        "params": {
            "path": "dlz-user-container/data8.csv"
        },
        "connectionSpec": {
            "id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
            "version": "1.0"
        }
    }'
Eigenschap
Beschrijving
name
De naam van uw Data Landing Zone bronverbinding.
data.format
De indeling van de gegevens die u naar het platform wilt verzenden.
params.path
Het pad naar het bestand dat u naar het platform wilt verzenden.
connectionSpec.id
De verbindingsspecificatie-id die overeenkomt met Data Landing Zone . Deze vaste id is: 26f526f2-58f4-4712-961d-e41bf1ccc0e8 .

Reactie

Een succesvolle reactie keert het unieke herkenningsteken (id) van de pas gecreëerde bronverbinding terug. Deze id is vereist in de volgende zelfstudie om een gegevensstroom te maken.

{
    "id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
    "etag": "\"1400d460-0000-0200-0000-613be3520000\""
}

Volgende stappen

Aan de hand van deze zelfstudie hebt u uw Data Landing Zone -gegevens opgehaald, de bestandsstructuur verkend om het bestand te zoeken dat u naar Platform wilt verzenden, en een bronverbinding gemaakt om uw gegevens naar Platform te brengen. U kunt nu aan het volgende leerprogramma te werk gaan, waar u zult leren hoe te een dataflow creëren om de gegevens van de wolkenopslag aan Platform te brengen gebruikend Flow Service API.

recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089