Komma igång med REST APIs getting-started-with-rest-apis

Information om allmänna krav, autentisering, valfria frågeparametrar, begäran URLs och andra referenser.

API-krav och Recommendations api-requirements-recommendations

Observera följande när du arbetar med Audience Manager API -kod:

  • Begäranparametrar: alla begäranparametrar är obligatoriska om inte annat anges.
  • Begäranrubriker: När du använder Adobe Developer-tokens måste du ange x-api-key-rubriken. Du kan hämta nyckeln API genom att följa instruktionerna på sidan Integrering av tjänstkonto.
  • JSONinnehållstyp: Ange content-type: application/json och accept: application/json i koden.
  • Begäranden och svar: Skicka begäranden som ett korrekt formaterat JSON -objekt. Audience Manager svarar med JSON formaterade data. Serversvar kan innehålla begärda data, en statuskod eller båda.
  • Åtkomst: Din Audience Manager-konsult kommer att förse dig med ett klient-ID och en nyckel som gör att du kan göra API förfrågningar.
  • Dokumentation och kodexempel: Text i kursiv representerar en variabel som du anger eller skickar in när du skapar eller tar emot API-data. Ersätt kursiv-text med din egen kod, parametrar eller annan obligatorisk information.

Autentisering authentication

Audience Manager REST APIs har stöd för tre autentiseringsmetoder.

IMPORTANT
Beroende på din autentiseringsmetod måste du justera din begäran URLs därefter. I avsnittet Miljö finns mer information om värdnamnen som du bör använda.

OAuth Server-till-Server-autentisering med Adobe Developer oauth-adobe-developer

I det här avsnittet beskrivs hur du samlar in de inloggningsuppgifter som krävs för att autentisera Audience Manager API-anrop, vilket beskrivs i nedanstående flödesschema. Du kan samla de flesta nödvändiga autentiseringsuppgifter i den första engångsinställningen. Åtkomsttoken måste dock uppdateras var 24:e timme.

Audience Manager autentiseringsflödesdiagram.

Adobe Developer - översikt developer-overview

Adobe Developer är Adobe utvecklares ekosystem och community. Den innehåller API:er för alla Adobe-produkter.

Detta är det rekommenderade sättet att konfigurera och använda Adobe APIs.

Förutsättningar prerequisites-server-to-server

Innan du kan konfigurera OAuth Server-to-Server-autentisering måste du kontrollera att du har åtkomst till Adobe Developer Console i Adobe Developer. Kontakta din organisations administratör för åtkomstbegäranden.

Autentisering oauth

Följ stegen nedan för att konfigurera OAuth Server-to-Server-autentisering med Adobe Developer:

  1. Logga in på Adobe Developer Console.
  2. Följ stegen i implementeringsguiden för autentiseringsuppgifter för OAuth Server-till-server.
  3. Prova anslutningen genom att ringa ditt första API-samtal baserat på instruktionerna från Steg 3.
NOTE
Om du vill konfigurera och arbeta med Audience Manager REST APIs automatiskt kan du rotera klienthemligheter programmatiskt. Mer information finns i utvecklardokumentationen.

Lägga till Audience Manager API i ett projekt add-aam-api-to-project

Gå till Adobe Developer Console och logga in med din Adobe ID. Följ sedan stegen som beskrivs i självstudiekursen om att skapa ett tomt projekt i Adobe Developer Console-dokumentationen.

När du har skapat ett nytt projekt väljer du Add API på skärmen Project Overview.

TIP
Om du har etablerat dig för flera organisationer använder du organisationsväljaren i det övre högra hörnet av gränssnittet för att kontrollera att du är i den organisation du behöver.

Developer Console-skärmen med alternativet Lägg till API markerat.

Skärmen Add an API visas. Markera produktikonen för Adobe Experience Cloud och välj sedan Audience Manager API innan du väljer Next.

Välj Audience Manager-API.

TIP
Välj alternativet View docs om du vill navigera i ett separat webbläsarfönster till den fullständiga Audience Manager API-referensdokumentationen.

Välj autentiseringstypen OAuth Server-till-server select-oauth-server-to-server

Välj sedan autentiseringstypen för att generera åtkomsttoken och få åtkomst till Audience Manager-API:t.

IMPORTANT
Välj metoden OAuth Server-to-Server eftersom det här är den enda metod som stöds för att gå framåt. Metoden Service Account (JWT) är föråldrad. Även om integreringar med JWT-autentiseringsmetoden fortsätter att fungera fram till 1 januari 2025 rekommenderar Adobe starkt att du migrerar befintliga integreringar till den nya OAuth Server-till-Server-metoden före detta datum.

Välj OAuth-autentiseringsmetod.

Välj produktprofiler för integreringen select-product-profiles

Välj produktprofiler på skärmen Configure API. Integreringens tjänstkonto får tillgång till detaljerade funktioner via de produktprofiler som väljs här.

Välj produktprofiler för din integrering.

Välj Save configured API när du är klar.

Samla in inloggningsuppgifter gather-credentials

När API:t har lagts till i projektet visar Audience Manager API-sidan för projektet följande autentiseringsuppgifter som krävs i alla anrop till API:er för Audience Manager:

Integreringsinformation när du har lagt till ett API i Developer Console.

  • {API_KEY} (Client ID)
  • {ORG_ID} (Organization ID)

Generera en åtkomsttoken generate-access-token

Nästa steg är att generera en {ACCESS_TOKEN}-autentiseringsuppgift som kan användas i API-anrop från Audience Manager. Till skillnad från värdena för {API_KEY} och {ORG_ID} måste en ny token genereras var 24:e timme för att du ska kunna fortsätta använda Audience Manager API:er. Välj Generate access token enligt nedan.

Visa hur du genererar åtkomsttoken

Testa ett API-anrop test-api-call

När du har hämtat din token för autentisering av innehavare utför du ett API-anrop för att testa att du nu kan komma åt API:er för Audience Manager.

  1. Navigera till API-referensdokumentationen.

  2. Välj Authorize och klistra in åtkomsttoken som du fick i steget Generera åtkomsttoken.

    Auktorisera API-anrop

  3. Utför ett GET-anrop till API-slutpunkten /datasources för att hämta en lista över alla globalt tillgängliga datakällor, vilket anges i API-referensdokumentationen. Välj Try it out, följt av Execute, så som visas nedan.

    Utför API-anrop

recommendation-more-help
API-begäran
code language-shell
curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'
API-svar om rätt innehavartoken används

När du använder en arbetsåtkomsttoken returnerar API-slutpunkten ett 200-svar tillsammans med ett svarstext som innehåller alla globala datakällor som din organisation har tillgång till.

code language-json
[
  {
    "pid": 1794,
    "name": "testdatasource1",
    "description": "Test data source",
    "status": "ACTIVE",
    "integrationCode": "test_ds1",
    "dataExportRestrictions": [],
    "updateTime": 1595340792000,
    "crUID": 0,
    "upUID": 15910,
    "linkNamespace": false,
    "type": "GENERAL",
    "subIdType": "CROSS_DEVICE_PERSON",
    "inboundS2S": true,
    "outboundS2S": true,
    "useAudienceManagerVisitorID": false,
    "allowDataSharing": true,
    "masterDataSourceIdProvider": true,
    "uniqueTraitIntegrationCodes": false,
    "uniqueSegmentIntegrationCodes": false,
    "marketingCloudVisitorIdVersion": 0,
    "idType": "CROSS_DEVICE",
    "samplingEndTime": 1596550392825,
    "allowDeviceGraphSharing": false,
    "supportsAuthenticatedProfile": true,
    "deviceGraph": false,
    "authenticatedProfileName": "testdatasource1",
    "deviceGraphName": "",
    "customNamespaceId": 29769,
    "customNamespaceCode": "silviu_ds1",
    "customerProfileDataRetention": 62208000,
    "samplingStartTime": 1595340792825,
    "dataSourceId": 29769,
    "containerIds": [],
    "samplingEnabled": false
  },
  {
    "pid": 1794,
    "name": "AAM Test Company Audiences",
    "description": "Automatically generated trait data source",
    "status": "ACTIVE",
    "integrationCode": "adobe-provided",
    "dataExportRestrictions": [
      "PII"
    ],

    [...]

[Föråldrat]{class="badge negative"}JWT (Service Account) Autentisering med Adobe Developer jwt

Visa information om den borttagna JWT (Service Account)-metoden för att hämta autentiseringstoken.

Adobe Developer - översikt adobeio

Adobe Developer är Adobe utvecklares ekosystem och community. Den innehåller API:er för alla Adobe-produkter.

Detta är det rekommenderade sättet att konfigurera och använda Adobe APIs.

Förutsättningar prerequisites

Innan du kan konfigurera JWT-autentisering måste du kontrollera att du har åtkomst till Adobe Developer Console i Adobe Developer. Kontakta din organisations administratör för åtkomstbegäranden.

Autentisering auth

Följ stegen nedan för att konfigurera JWT (Service Account)-autentisering med Adobe Developer:

  1. Logga in på Adobe Developer Console.
  2. Följ stegen i Anslutning till tjänstkonto.
  3. Prova anslutningen genom att ringa ditt första API-samtal baserat på instruktionerna från Steg 3.
note note
NOTE
Om du vill konfigurera och arbeta med Audience Manager REST APIs automatiskt kan du generera JWT programmatiskt. Mer information finns i JWT-autentisering (tjänstkonto).

RBAC-behörigheter för tekniskt konto

Om ditt Audience Manager-konto använder rollbaserad åtkomstkontroll måste du skapa ett Audience Manager-tekniskt användarkonto och lägga till det i Audience Manager RBAC-gruppen som gör API-anropen.

Följ stegen nedan för att skapa ett tekniskt användarkonto och lägga till det i en RBAC-grupp:

  1. Ring GET till https://aam.adobe.io/v1/users/self. Anropet skapar ett tekniskt användarkonto som du kan se på sidan Admin Console på sidan Users.

    tekniskt konto

  2. Logga in på ditt Audience Manager-konto och lägg till det tekniska användarkontot i användargruppen som ska göra API-anropen.

[Föråldrat]{class="badge negative"}OAuth-autentisering (inaktuell) oauth-deprecated

Visa information om den inaktuella, gamla autentiseringsmetoden OAuth för att hämta autentiseringstoken.
note warning
WARNING
Audience Manager REST API tokenautentisering och förnyelse via OAuth 2.0 är nu föråldrat.
Använd JWT-autentisering (tjänstkonto) i stället.

Audience Manager REST API följer OAuth 2.0 standarder för tokenautentisering och förnyelse. I avsnitten nedan beskrivs hur du autentiserar och börjar arbeta med API.

Skapa en allmän API-användare requirements

Vi rekommenderar att du skapar ett separat, tekniskt användarkonto för att arbeta med Audience Manager APIs. Det här är ett generiskt konto som inte är kopplat till eller kopplat till en viss användare i organisationen. Den här typen av API-användarkonto hjälper dig att uppnå två saker:

  • Identifiera vilken tjänst som anropar API (t.ex. samtal från dina appar som använder våra API eller från andra verktyg som gör API-förfrågningar).
  • Ge oavbruten åtkomst till API. Ett konto som är knutet till en viss person kan tas bort när de lämnar företaget. Detta förhindrar dig från att arbeta med tillgänglig API-kod. Ett generiskt konto som inte är kopplat till en viss medarbetare hjälper dig att undvika det här problemet.

Ett exempel eller ett användningsfall för den här typen av konto är att du vill ändra många segment samtidigt med grupphanteringsverktygen. För att göra detta behöver ditt användarkonto API åtkomst. I stället för att lägga till behörigheter till en viss användare skapar du ett icke-specifikt API-användarkonto som har rätt autentiseringsuppgifter, nyckel och hemlighet för att ringa API-anrop. Detta är också användbart om du utvecklar egna program som använder Audience Manager APIs.

Arbeta med din Audience Manager-konsult för att konfigurera ett generiskt, API-skyddat användarkonto.

Lösenordsautentisering password-authentication-workflow

Lösenordsautentisering ger säker åtkomst till REST API. Stegen nedan visar arbetsflödet för lösenordsautentisering från en JSON-klient i webbläsaren.

note tip
TIP
Kryptera åtkomst- och uppdateringstoken om du lagrar dem i en databas.

Steg 1: Begär API åtkomst

Kontakta din Partner Solutions Manager. De ger dig ett API klient-ID och en hemlighet. ID:t och hemligheten autentiserar dig för API.

Obs! Om du vill få en uppdateringstoken anger du det när du begär åtkomst till API.

Steg 2: Begär token

Skicka en tokenbegäran med den önskade JSON-klienten. När du skapar begäran:

  • Använd metoden POST för att anropa https://api.demdex.com/oauth/token.
  • Konvertera ditt klient-ID och hemlighet till en base-64-kodad sträng. Separera ID:t och hemligheten med ett kolon under konverteringsprocessen. Autentiseringsuppgifterna testId : testSecret konverteras till exempel till dGVzdElkOnRlc3RTZWNyZXQ=.
  • Skicka in HTTP headers Authorization:Basic <base-64 clientID:clientSecret> och Content-Type: application/x-www-form-urlencoded . Din rubrik kan till exempel se ut så här:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Ställ in begärandetexten enligt följande:

    grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Steg 3: Ta emot token

Svaret JSON innehåller din åtkomsttoken. Svaret bör se ut så här:

code language-json
{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

Nyckeln expires_in representerar antalet sekunder tills åtkomsttoken upphör att gälla. Som bästa praxis bör du använda korta förfallotider för att begränsa exponeringen om token någonsin exponeras.

Uppdatera token refresh-token

Uppdatera tokens förnya API-åtkomsten när den ursprungliga token har upphört att gälla. Om det efterfrågas innehåller svaret JSON i lösenordsarbetsflödet en uppdateringstoken. Om du inte får någon uppdateringstoken skapar du en ny under lösenordsautentiseringsprocessen.

Du kan också använda en uppdateringstoken för att generera en ny token innan den befintliga åtkomsttoken upphör att gälla.

Om din åtkomsttoken har upphört att gälla får du ett 401 Status Code och följande rubrik i svaret:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

I följande steg beskrivs arbetsflödet för att använda en uppdateringstoken för att skapa en ny åtkomsttoken från en JSON-klient i webbläsaren.

Steg 1: Begär ny token

Skicka en begäran om uppdateringstoken med den önskade JSON-klienten. När du skapar begäran:

  • Använd metoden POST för att anropa https://api.demdex.com/oauth/token.
  • Konvertera ditt klient-ID och hemlighet till en base-64-kodad sträng. Separera ID:t och hemligheten med ett kolon under konverteringsprocessen. Autentiseringsuppgifterna testId : testSecret konverteras till exempel till dGVzdElkOnRlc3RTZWNyZXQ=.
  • Skicka HTTP-rubrikerna Authorization:Basic <base-64 clientID:clientSecret> och Content-Type: application/x-www-form-urlencoded. Din rubrik kan till exempel se ut så här:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • Ange grant_type:refresh_token i begärandetexten och skicka den uppdateringstoken som du fick i din tidigare åtkomstbegäran. Begäran ska se ut så här:
    grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Steg 2: Ta emot den nya token

Svaret JSON innehåller din nya åtkomsttoken. Svaret bör se ut så här:

code language-json
{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Auktoriseringskod och implicit autentisering authentication-code-implicit

Audience Manager REST API stöder auktoriseringskod och implicit autentisering. Om du vill använda de här åtkomstmetoderna måste dina användare logga in på https://api.demdex.com/oauth/authorize för att få tillgång till och uppdatera tokens.

Gör autentiserade API förfrågningar authenticated-api-requests

Krav för att anropa API-metoder när du har tagit emot en autentiseringstoken.

Så här anropar du mot de tillgängliga API-metoderna:

Valfria API-frågeparametrar optional-api-query-parameters

Ange de valfria parametrar som är tillgängliga för metoder som returnerar alla egenskaper för ett objekt.

Du kan använda de här valfria parametrarna med API-metoder som returnerar all -egenskaper för ett objekt. Ange dessa alternativ i begärandesträngen när du skickar frågan till API.

Parameter
Beskrivning
page
Returnerar resultat per sidnummer. Numreringen börjar vid 0.
pageSize
Anger antalet svarsresultat som returneras av begäran (10 är standard).
sortBy
Sorterar och returnerar resultat enligt den angivna JSON-egenskapen.
descending
Sorterar och returnerar resultat i fallande ordning. ascending är standard.
search
Returnerar resultat baserat på den angivna strängen som du vill använda som sökparameter. Anta att du vill hitta resultat för alla modeller som har ordet "Test" i något av värdefälten för det objektet. Din exempelbegäran kan se ut så här: GET https://aam.adobe.io/v1/models/?search=Test. Du kan söka efter alla värden som returneras av en get all-metod.
folderId
Returnerar alla ID:n för traits i den angivna mappen. Inte tillgängligt för alla metoder.
permissions

Returnerar en lista med segment baserat på den angivna behörigheten. READ är standard. Behörigheterna är:

  • READ : Returnera och visa information om ett segment.
  • WRITE : Använd PUT för att uppdatera ett segment.
  • CREATE : Använd POST för att skapa ett segment.
  • DELETE: Ta bort ett segment. Kräver åtkomst till eventuella underliggande egenskaper. Du måste till exempel ha behörighet att ta bort de egenskaper som tillhör ett segment om du vill ta bort det.

Ange flera behörigheter med separata nyckelvärdepar. Om du till exempel vill returnera en lista med segment med endast READ och WRITE behörigheter skickar du in "permissions":"READ", "permissions":"WRITE" .

includePermissions
(Boolean) Ange true om du vill returnera dina behörigheter för segmentet. Standardvärdet är false.

En anteckning om sidalternativ

När sidinformationen inte är angiven returnerar begäran JSON som resultat i en matris. Om sidinformationen anges kapslas den returnerade listan in i ett JSON-objekt som innehåller information om det totala resultatet och den aktuella sidan. Din exempelbegäran med sidalternativ kan se ut ungefär så här:

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs api-urls

URLs för begäranden, mellanlagrings- och produktionsmiljöer samt versioner.

Begäran URLs request-urls

I följande tabell visas begäran URLs som används för att skicka API-begäranden per metod.

Beroende på vilken autentiseringsmetod du använder måste du justera din begäran URLs enligt tabellerna nedan.

Begär URLs för [Rekommenderad]{class="badge positive"}[Föråldrat]{class="badge negative"}Autentisering av JWT via Adobe Developer request-urls-jwt

API-metoder
Begäran URL
Algorithmic Modeling
https://aam.adobe.io/v1/models/
Data Source
https://aam.adobe.io/v1/datasources/
Derived Signals
https://aam.adobe.io/v1/signals/derived/
Destinations
https://aam.adobe.io/v1/destinations/
Domains
https://aam.adobe.io/v1/partner-sites/
Folders
Traits: https://aam.adobe.io/v1/folders/traits /
Segments: https://aam.adobe.io/v1/folders/segments /
Schema
https://aam.adobe.io/v1/schemas/
Segments
https://aam.adobe.io/v1/segments/
Traits
https://aam.adobe.io/v1/traits/
Trait Types
https://aam.adobe.io/v1/customer-trait-types
Taxonomy
https://aam.adobe.io/v1/taxonomies/0/

Begär URLs för [borttagen]{class="badge negative"}Autentisering av OAuth request-urls-oauth

API-metoder
Begäran URL
Algorithmic Modeling
https://api.demdex.com/v1/models/
Data Source
https://api.demdex.com/v1/datasources/
Derived Signals
https://api.demdex.com/v1/signals/derived/
Destinations
https://api.demdex.com/v1/destinations/
Domains
https://api.demdex.com/v1/partner-sites/
Folders
Traits: https://api.demdex.com/v1/folders/traits /
Segments: https://api.demdex.com/v1/folders/segments /
Schema
https://api.demdex.com/v1/schemas/
Segments
https://api.demdex.com/v1/segments/
Traits
https://api.demdex.com/v1/traits/
Trait Types
https://api.demdex.com/v1/customer-trait-types
Taxonomy
https://api.demdex.com/v1/taxonomies/0/

Miljö environments

Audience Manager API ger åtkomst till olika arbetsmiljöer. Dessa miljöer hjälper dig att testa kod mot separata databaser utan att påverka livedata i produktionen. I följande tabell visas tillgängliga API-miljöer och motsvarande resursvärdnamn.

Beroende på vilken autentiseringsmetod du använder måste du justera miljön URLs enligt tabellen nedan.

Miljö
Värdnamn för JWT-autentisering
Värdnamn för OAuth-autentisering
Produktion
https://aam.adobe.io/...
https://api.demdex.com/...
Beta
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
NOTE
Betamiljön Audience Manager är en mindre, fristående version av produktionsmiljön. Alla data som du vill testa måste anges och samlas in i den här miljön.

Versioner versions

Nya versioner av dessa API släpps regelbundet. En ny version ökar versionsnumret för API. Versionsnumret refereras i begäran URL som v<version number>, vilket visas i följande exempel:

https://<host>/v1/...

Definierade svarskoder response-codes-defined

HTTP statuskoder och svarstext som returneras av Audience Manager REST API.

Svarskod-ID
Svarstext
Definition
200
OK
Begäran har bearbetats. Returnerar förväntat innehåll eller data om det behövs.
201
Created
Resursen skapades. Returnerar för PUT- och POST-begäranden.
204
No Content
Resursen har tagits bort. Svarstexten är tom.
400
Bad Request
Servern förstod inte begäran. Vanligtvis på grund av felaktig syntax. Kontrollera din begäran och försök igen.
403
Forbidden
Du har inte åtkomst till resursen.
404
Not Found
Det gick inte att hitta resursen för den angivna sökvägen.
409
Conflict
Begäran kunde inte slutföras på grund av en konflikt med resursens tillstånd.
500
Server Error
Servern påträffade ett oväntat fel som gjorde att den inte kunde utföra begäran.
de293fbf-b489-49b0-8daa-51ed303af695