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

Information om allmänna krav, autentisering, valfria frågeparametrar, begäran URLsoch 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: vid användning Adobe Developer variabler måste du ange x-api-key header. Du kan få dina API genom att följa instruktionerna i Integrering av tjänstkonto sida.
  • JSONinnehållstyp: Ange content-type: application/json och accept: application/json i koden.
  • Förfrågningar och svar: Skicka begäranden som korrekt formaterade JSON -objekt. Audience Manager svarar med JSON data. Serversvar kan innehålla begärda data, en statuskod eller båda.
  • Åtkomst: Dina Audience Manager konsulten ger dig ett klient-ID och en nyckel som gör att du kan API förfrågningar.
  • Exempel på dokumentation och kod: Text in kursiv representerar en variabel som du anger eller skickar in när du skapar eller tar emot API data. Ersätt kursiv text med egen kod, egna parametrar eller annan obligatorisk information.

Autentisering authentication

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

IMPORTANT
Beroende på din autentiseringsmetod måste du justera din begäran URLs i enlighet med detta. Se Miljö om du vill ha information om värdnamn 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 verifiering, se till att du har åtkomst till Adobe Developer Console in 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 Implementeringshandbok för OAuth Server-till-Server-autentiseringsuppgifter.
  3. Testa anslutningen genom att göra din första API samtal baserat på instruktionerna från Steg 3.
NOTE
Konfigurera och arbeta med Audience Manager REST APIs på ett automatiserat sätt kan ni rotera kundhemligheter programmatiskt. Se dokumentation för utvecklare för detaljerade anvisningar.

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 instruktionerna i självstudiekursen på skapa ett tomt projekt i dokumentationen för Adobe Developer Console.

När du har skapat ett nytt projekt väljer du Add APIProject Overview skärm.

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.

The Add an API visas. Markera produktikonen för Adobe Experience Cloud och välj sedan Audience Manager API före markering Next.

Välj Audience Manager API.

TIP
Välj View docs alternativ för att navigera i ett separat webbläsarfönster till det fullständiga Referenshandbok för Audience Manager API.

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 OAuth Server-to-Server eftersom det här är den enda metod som stöds för att gå framåt. The Service Account (JWT) -metoden är inaktuell. Ä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

I Configure API väljer du produktprofiler. 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 redo.

Samla in inloggningsuppgifter gather-credentials

När API:t har lagts till i projektet Audience Manager API På projektsidan visas följande autentiseringsuppgifter som krävs för 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 skapa en {ACCESS_TOKEN} autentiseringsuppgifter för användning i API-anrop för 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, vilket visas 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-referensdokumentation.

  2. Välj Authorize och klistra in åtkomsttoken som du fick i generera åtkomsttoken steg.

    Auktorisera API-anrop

  3. Utför ett GET-samtal till /datasources API-slutpunkt för att hämta en lista över alla globalt tillgängliga datakällor, vilket anges i API-referensdokumentation. Välj Try it out, följt av Execute, vilket 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) metod 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 verifiering, se till att du har åtkomst till Adobe Developer Console in 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. Testa anslutningen genom att göra din första API samtal baserat på instruktionerna från Steg 3.
note note
NOTE
Konfigurera och arbeta med Audience Manager REST APIs på ett automatiserat sätt kan du generera JWT programmatiskt. Se JWT-autentisering (tjänstkonto) för detaljerade anvisningar.

RBAC-behörigheter för tekniskt konto

Om ditt Audience Manager-konto använder Rollbaserad åtkomstkontrollmåste du skapa ett Audience Manager-användarkonto och lägga till det i Audience Manager RBAC-gruppen som ska göra API-anropen.

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

  1. Gör en GET ring till https://aam.adobe.io/v1/users/self. Samtalet skapar ett tekniskt användarkonto som du kan se i Admin Console, i Users sida.

    tekniskt konto

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

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

Visa information om det gamla inaktuella OAuth Autentiseringsmetod 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.

The 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 APIs.

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. Detta är ett generiskt konto som inte är kopplat till eller kopplat till en viss användare i organisationen. Den här typen av API Med användarkontot kan du uppnå två saker:

  • Identifiera vilken tjänst som anropar API (t.ex. samtal från appar som använder våra APIeller andra verktyg som API förfrågningar).
  • Oavbruten åtkomst till APIs. 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ängliga 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ändningsexempel för den här typen av konto är att du vill ändra många segment samtidigt med Masshanteringsverktyg. 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 en icke-specifik, API användarkonto som har rätt autentiseringsuppgifter, nyckel och hemlighet att skapa API samtal. Detta är också användbart om du utvecklar egna program som använder Audience Manager APIs.

Arbeta med dina Audience Manager konsult för att skapa en allmän API-only användarkonto.

Lösenordsautentisering password-authentication-workflow

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

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

Steg 1: Begäran API Åtkomst

Kontakta din Partner Solutions Manager. De ger dig en API klient-ID och 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 API åtkomst.

Steg 2: Begär token

Skicka en tokenbegäran med din egen inställning JSON klient. När du skapar begäran:

  • Använd en POST metod 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. Inloggningsuppgifterna testId : testSecret konvertera till dGVzdElkOnRlc3RTZWNyZXQ=.
  • Skicka in HTTP headers Authorization:Basic <base-64 clientID:clientSecret> och Content-Type: application/x-www-form-urlencoded . Sidhuvudet kan 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

The JSON -svaret 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"
}

The 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 förnyelse av tokens API åtkomst när den ursprungliga token har upphört att gälla. Om det efterfrågas kan svaret JSON i lösenordsarbetsflödet innehåller 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 en 401 Status Code och följande rubrik i svaret:

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

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

Steg 1: Begär ny token

Skicka en begäran om en uppdateringstoken till dig JSON klient. När du skapar begäran:

  • Använd en POST metod 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. Inloggningsuppgifterna testId : testSecret konvertera till dGVzdElkOnRlc3RTZWNyZXQ=.
  • Skicka in HTTP-rubriker Authorization:Basic <base-64 clientID:clientSecret> och Content-Type: application/x-www-form-urlencoded. Sidhuvudet kan se ut så här:
    Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
    Content-Type: application/x-www-form-urlencoded
  • I begärandetexten anger du grant_type:refresh_token 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

The JSON -svaret 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

The Audience Manager REST API stöder auktoriseringskod och implicit autentisering. Om du vill använda dessa åtkomstmetoder måste användarna logga in på https://api.demdex.com/oauth/authorize för att få åtkomst till och uppdatera tokens.

Gör autentiserad API Begäranden authenticated-api-requests

Anropskrav API metoder när du har fått en autentiseringstoken.

Göra anrop mot tillgängliga API metoder:

Valfritt 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 alla egenskaper för ett objekt. Ange dessa alternativ i begärandesträngen när frågan skickas 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 angivet JSON -egenskap.
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 enget all".
folderId
Returnerar alla ID för traits inuti 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 READ och WRITE endast behörigheter, skicka in "permissions":"READ", "permissions":"WRITE" .

includePermissions
(Boolean) Ange som true för att returnera dina behörigheter för segmentet. Standard är false.

En anteckning om sidalternativ

När sidinformation är inte anges returnerar begäran normal JSON resulterar i en array. Om sidinformation är anges, radbryts den returnerade listan i en 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 förfrågningar, staging- och produktionsmiljöer samt versioner.

Begäran URLs request-urls

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

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

Begäran URLs för [Rekommenderas]{class="badge positive"}[Föråldrat]{class="badge negative"}JWT Autentisering 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 /
Segment: 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äran URLs för [Föråldrat]{class="badge negative"}OAuth Autentisering 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 /
Segment: 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

The Audience Manager APIs 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 de 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
The Audience Manager betamiljö ä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 APIs släpps enligt ett regelbundet schema. En ny release ökar API versionsnummer. Versionsnumret refereras i begäran URL as v<version number> som 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 förfrågningar.
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