Creare una configurazione di destinazione

Questa pagina esemplifica la richiesta API e il payload che è possibile utilizzare per creare la propria configurazione di destinazione, utilizzando l'endpoint API /authoring/destinations.

Per una descrizione dettagliata delle funzionalità che puoi configurare tramite questo endpoint, leggi i seguenti articoli:

IMPORTANT
Tutti i nomi e i valori dei parametri supportati da Destination SDK sono con distinzione tra maiuscole e minuscole. Per evitare errori di distinzione tra maiuscole e minuscole, utilizza i nomi e i valori dei parametri esattamente come mostrato nella documentazione.

Guida introduttiva alle operazioni API di configurazione di destinazione get-started

Prima di continuare, consulta la guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all'API, tra cui come ottenere l'autorizzazione di authoring della destinazione richiesta e le intestazioni richieste.

Creare una configurazione di destinazione create

È possibile creare una nuova configurazione di destinazione effettuando una richiesta POST all'endpoint /authoring/destinations.

TIP
Endpoint API: platform.adobe.io/data/core/activation/authoring/destinations

Formato API

POST /authoring/destinations

La richiesta seguente crea una nuova configurazione di destinazione Amazon S3, configurata dai parametri forniti nel payload. Il payload seguente include tutti i parametri per le destinazioni basate su file accettate dall'endpoint /authoring/destinations.

Tieni presente che non è necessario aggiungere tutti i parametri alla chiamata API e che il payload è personalizzabile in base ai requisiti API.

Richiesta
code language-shell
curl -X POST https://platform.adobe.io/data/core/activation/authoring/destinations \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '
{
   "name":"Amazon S3 destination with predefined CSV formatting options",
   "description":"Amazon S3 destination with predefined CSV formatting options",
   "status":"TEST",
   "customerAuthenticationConfigurations":[
      {
         "authType":"S3"
      }
   ],
   "customerDataFields":[
      {
         "name":"bucket",
         "title":"Enter the name of your Amazon S3 bucket",
         "description":"Amazon S3 bucket name",
         "type":"string",
         "isRequired":true,
         "readOnly":false,
         "hidden":false
      },
      {
         "name":"path",
         "title":"Enter the path to your S3 bucket folder",
         "description":"Enter the path to your S3 bucket folder",
         "type":"string",
         "isRequired":true,
         "pattern":"^[A-Za-z]+$",
         "readOnly":false,
         "hidden":false
      },
      {
         "name":"compression",
         "title":"Compression format",
         "description":"Select the desired file compression format.",
         "type":"string",
         "isRequired":true,
         "readOnly":false,
         "enum":[
            "SNAPPY",
            "GZIP",
            "DEFLATE",
            "NONE"
         ]
      },
      {
         "name":"fileType",
         "title":"Select a fileType",
         "description":"Select fileType",
         "type":"string",
         "isRequired":true,
         "readOnly":false,
         "hidden":false,
         "enum":[
            "csv",
            "json",
            "parquet"
         ],
         "default":"csv"
      }
   ],
   "uiAttributes":{
      "documentationLink":"https://www.adobe.com/go/destinations-amazon-s3-en",
      "category":"cloudStorage",
      "icon":{
         "key":"amazonS3"
      },
      "connectionType":"S3",
      "frequency":"Batch"
   },
   "destinationDelivery":[
      {
         "deliveryMatchers":[
            {
               "type":"SOURCE",
               "value":[
                  "batch"
               ]
            }
         ],
         "authenticationRule":"CUSTOMER_AUTHENTICATION",
         "destinationServerId":"{{destinationServerId}}"
      }
   ],
   "schemaConfig":{
      "profileRequired":true,
      "segmentRequired":true,
      "identityRequired":true
   },
   "batchConfig":{
      "allowMandatoryFieldSelection":true,
      "allowDedupeKeyFieldSelection":true,
      "defaultExportMode":"DAILY_FULL_EXPORT",
      "allowedExportMode":[
         "DAILY_FULL_EXPORT",
         "FIRST_FULL_THEN_INCREMENTAL"
      ],
      "allowedScheduleFrequency":[
         "DAILY",
         "EVERY_3_HOURS",
         "EVERY_6_HOURS",
         "EVERY_8_HOURS",
         "EVERY_12_HOURS",
         "ONCE"
      ],
      "defaultFrequency":"DAILY",
      "defaultStartTime":"00:00",
      "filenameConfig":{
         "allowedFilenameAppendOptions":[
            "SEGMENT_NAME",
            "DESTINATION_INSTANCE_ID",
            "DESTINATION_INSTANCE_NAME",
            "ORGANIZATION_NAME",
            "SANDBOX_NAME",
            "DATETIME",
            "CUSTOM_TEXT"
         ],
         "defaultFilenameAppendOptions":[
            "DATETIME"
         ],
         "defaultFilename":"%DESTINATION%_%SEGMENT_ID%"
      },
      "backfillHistoricalProfileData":true
   }
}'
table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3 11-row-3 12-row-3 13-row-3 14-row-3 15-row-3 16-row-3 17-row-3 18-row-3 19-row-3 20-row-3 21-row-3 22-row-3 23-row-3 24-row-3 25-row-3 26-row-3 27-row-3 28-row-3 29-row-3 30-row-3 31-row-3 layout-auto
Parametro Tipo Descrizione
name Stringa Indica il titolo della destinazione nel catalogo di Experienci Platform.
description Stringa Fornisci una descrizione che Adobe utilizzerà nel catalogo delle destinazioni Experience Platform per la tua scheda di destinazione. Puntare a non più di 4-5 frasi. Immagine dell'interfaccia utente di Platform con la descrizione della destinazione. {width="100" modal="regular"}
status Stringa Indica lo stato del ciclo di vita della scheda di destinazione. I valori accettati sono TEST, PUBLISHED e DELETED. Utilizza TEST quando configuri per la prima volta la destinazione.
customerAuthenticationConfigurations.authType Stringa Indica la configurazione utilizzata per autenticare i clienti Experienci Platform nel server di destinazione. Per informazioni dettagliate sui tipi di autenticazione supportati, vedere configurazione dell'autenticazione del cliente.
customerDataFields.name Stringa Immetti un nome per il campo personalizzato che stai presentando.

Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente. Immagine dell'interfaccia utente di Platform che mostra i campi dati del cliente. {width="100" modal="regular"}
customerDataFields.type Stringa Indica il tipo di campo personalizzato che si sta introducendo. I valori accettati sono string, object, integer.

Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente.
customerDataFields.title Stringa Indica il nome del campo, così come viene visualizzato dai clienti nell’interfaccia utente di Experience Platform.

Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente.
customerDataFields.description Stringa Fornisci una descrizione per il campo personalizzato. Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente.
customerDataFields.isRequired Booleano Indica se questo campo è obbligatorio nel flusso di lavoro di configurazione della destinazione.

Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente.
customerDataFields.enum Stringa Esegue il rendering del campo personalizzato come menu a discesa ed elenca le opzioni disponibili per l'utente.

Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente.
customerDataFields.default Stringa Definisce il valore predefinito da un elenco enum.
customerDataFields.pattern Stringa Se necessario, applica un pattern per il campo personalizzato. Utilizza espressioni regolari per applicare un pattern. Ad esempio, se gli ID cliente non includono numeri o trattini bassi, immetti ^[A-Za-z]+$ in questo campo.

Per informazioni dettagliate su queste impostazioni, vedere Campi dati cliente.
uiAttributes.documentationLink Stringa Fa riferimento alla pagina della documentazione nel Catalogo destinazioni per la tua destinazione. Utilizza https://www.adobe.com/go/destinations-YOURDESTINATION-en, dove YOURDESTINATION è il nome della tua destinazione. Per una destinazione denominata Moviestar, si utilizza https://www.adobe.com/go/destinations-moviestar-en. Tieni presente che questo collegamento funziona solo dopo che Adobe ha impostato la destinazione live e che la documentazione è stata pubblicata.

Per informazioni dettagliate su queste impostazioni, vedere Attributi dell'interfaccia utente. Immagine dell'interfaccia utente di Platform con il collegamento alla documentazione. {width="100" modal="regular"}
uiAttributes.category Stringa Fa riferimento alla categoria assegnata alla destinazione in Adobe Experience Platform. Per ulteriori informazioni, leggere Categorie di destinazione. Utilizzare uno dei valori seguenti: adobeSolutions, advertising, analytics, cdp, cloudStorage, crm, customerSuccess, database, dmp, ecommerce, email, emailMarketing, enrichment, livechat, marketingAutomation, mobile, personalization, protocols, social, streaming, subscriptions, surveys, tagManagers, voc, warehouses, payments.

Per informazioni dettagliate su queste impostazioni, vedere Attributi dell'interfaccia utente.
uiAttributes.connectionType Stringa

Il tipo di connessione, a seconda della destinazione. Valori supportati:

  • Server-to-server
  • Cloud storage
  • Azure Blob
  • Azure Data Lake Storage
  • S3
  • SFTP
  • DLZ
uiAttributes.frequency Stringa Si riferisce al tipo di esportazione dei dati supportato dalla destinazione. Impostato su Streaming per le integrazioni basate su API, oppure su Batch quando si esportano file nelle destinazioni.
identityNamespaces.externalId.acceptsAttributes Booleano Indica se i clienti possono mappare gli attributi di profilo standard all’identità che stai configurando.
identityNamespaces.externalId.acceptsCustomNamespaces Booleano Indica se i clienti possono mappare le identità appartenenti a spazi dei nomi personalizzati all'identità che si sta configurando.
identityNamespaces.externalId.transformation Stringa Non visualizzato nella configurazione di esempio. Utilizzato, ad esempio, quando il cliente Platform ha come attributo indirizzi e-mail semplici e la tua piattaforma accetta solo e-mail con hash. Qui puoi fornire la trasformazione da applicare (ad esempio, trasformare l’e-mail in minuscolo, quindi in hash).
identityNamespaces.externalId.acceptedGlobalNamespaces - Indica quali spazi dei nomi di identità standard (ad esempio, IDFA) i clienti possono mappare all'identità che stai configurando.
Quando si utilizza acceptedGlobalNamespaces, è possibile utilizzare "requiredTransformation":"sha256(lower($))" per inserire indirizzi e-mail o numeri di telefono in minuscolo e con hash.
destinationDelivery.authenticationRule Stringa

Indica come Platform clienti si connettono alla destinazione. I valori accettati sono CUSTOMER_AUTHENTICATION, PLATFORM_AUTHENTICATION, NONE.

  • Utilizza CUSTOMER_AUTHENTICATION se i clienti di Platform accedono al tuo sistema tramite un nome utente e una password, un token Bearer o un altro metodo di autenticazione. Ad esempio, è possibile selezionare questa opzione se si seleziona anche authType: OAUTH2 o authType:BEARER in customerAuthenticationConfigurations.
  • Utilizzare PLATFORM_AUTHENTICATION se è presente un Adobe di autenticazione globale tra e la destinazione e il cliente Platform non deve fornire credenziali di autenticazione per connettersi alla destinazione. In questo caso, è necessario creare un oggetto credenziali utilizzando la configurazione credentials API.
  • Utilizza NONE se non è richiesta alcuna autenticazione per inviare dati alla piattaforma di destinazione.
destinationDelivery.destinationServerId Stringa instanceId del modello del server di destinazione utilizzato per questa destinazione.
backfillHistoricalProfileData Booleano Controlla se i dati storici del profilo vengono esportati quando i tipi di pubblico vengono attivati nella destinazione. Imposta sempre true.
segmentMappingConfig.mapUserInput Booleano Controlla se l’ID di mappatura del pubblico nel flusso di lavoro di attivazione della destinazione viene immesso dall’utente.
segmentMappingConfig.mapExperiencePlatformSegmentId Booleano Controlla se l’ID di mappatura del pubblico nel flusso di lavoro di attivazione della destinazione è l’ID del pubblico Experience Platform.
segmentMappingConfig.mapExperiencePlatformSegmentName Booleano Controlla se l’ID di mappatura del pubblico nel flusso di lavoro di attivazione della destinazione è il nome Experience Platform del pubblico.
segmentMappingConfig.audienceTemplateId Stringa instanceId del modello di metadati del pubblico utilizzato per questa destinazione.
schemaConfig.profileFields Array Quando si aggiunge profileFields predefinito come mostrato nella configurazione precedente, gli utenti avranno la possibilità di mappare gli attributi di Experience Platform agli attributi predefiniti sul lato della destinazione.
schemaConfig.profileRequired Booleano Utilizza true se gli utenti devono essere in grado di mappare gli attributi del profilo da Experience Platform ad attributi personalizzati sul lato della destinazione, come mostrato nella configurazione di esempio precedente.
schemaConfig.segmentRequired Booleano Usa sempre segmentRequired:true.
schemaConfig.identityRequired Booleano Utilizza true se gli utenti devono essere in grado di mappare gli spazi dei nomi delle identità dall'Experience Platform allo schema desiderato.
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con i dettagli della nuova configurazione di destinazione creata.

Gestione degli errori API

Gli endpoint API di Destination SDK seguono i principi generali dei messaggi di errore API di Experience Platform. Consulta Codici di stato API e errori di intestazione della richiesta nella guida alla risoluzione dei problemi di Platform.

Passaggi successivi

Dopo aver letto questo documento, sai come creare una nuova configurazione di destinazione tramite l'endpoint API Destination SDK /authoring/destinations.

Per ulteriori informazioni su cosa è possibile fare con questo endpoint, consulta i seguenti articoli:

Per capire dove questo endpoint si inserisce nel processo di authoring della destinazione, vedi i seguenti articoli:

recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6