REST API V2 Cookbook (Server-to-Server) rest-api-v2-cookbook-server-to-server

Kommunicera med Adobe Pass Service för Streaming App.

Samla in och skicka en unik enhets-ID för direktuppspelningsenheten enligt vad som krävs i huvudet AP-Device-Identifier.

Samla in och skicka korrekt information om direktuppspelningsenhet, inklusive källporten och enhetsspecifik information, enligt vad som krävs i rubriken X-Device-Info .

Samla in och skicka IP-adressen för direktuppspelningsenheten enligt vad som krävs i huvudet X-Forwarded-For.

Lagra parametrar som enhets-ID, klient-ID och klienthemlighet säkert i antingen Streaming App eller Programmer Service.

Formatera och skicka data i enlighet med MVPD-program och integrerade program, inklusive enhets-IP, källport, enhetsspecifik information, MRSS och valfria identifierare som ECID.

Underhåll och hantera säkert certifikat som delas med Adobe för krypterad överföring av användarmetadata.

Respektera autentiseringsprofilen och giltigheten för auktoriseringsbeslut vid cachelagring, och se till att autentiserings- och auktoriseringstillstånden ogiltigförklaras när de meddelas.

Returnera auktoriseringsbeslut och relevanta instruktioner till Streaming App.

Adobe Pass-tjänsten fungerar över flera geografiskt spridda datacenter i hela USA för att optimera prestanda och minimera latenstiden.

• Programmeringstjänsten bör anta en liknande infrastrukturstrategi som säkerställer svarstider med låg fördröjning från Adobe Pass.

Programmeraren måste tillhandahålla det offentliga IP-intervallet för sin produktionsmiljö.

• Dessa IP-adresser läggs till i ett tillåtelselista i Adobe Pass infrastruktur.

Programmerartjänsten måste begränsa DNS-cachning till högst 30 sekunder för att tillåta dynamisk omdirigering om Adobe behöver omdirigera trafik på grund av att ett datacenter inte är tillgängligt.

Det måste vara möjligt för testversioner innan driftsättning till produktion.

Det bör i sin tur i sin funktion vara likartat med produktionen, vilket möjliggör realistisk testning.

I idealfallet bör testmiljön anslutas till Adobe Pass testmiljöer för att

• Tillåt programmerare att testa mot Adobe infrastruktur.

• Gör det möjligt för Adobe att vid behov hjälpa till med testning och felsökning.

Hämta klientautentiseringsuppgifter: Programmeringstjänsten hämtar klientautentiseringsuppgifter genom att anropa slutpunkten /o/client/register.

• Programmerartjänsten eller programmerarappen måste lagra klientens autentiseringsuppgifter och använda dem i oändlighet när en åtkomsttoken behöver hämtas.

Hämta åtkomsttoken: Programmerartjänsten hämtar åtkomsttoken genom att anropa slutpunkten /o/client/token.

• Programmerartjänsten eller programmerarappen måste lagra och använda åtkomsttoken tills den upphör att gälla, sedan ta bort den och skaffa en ny.

Hämta profiler: Programmerartjänsten söker efter befintliga profiler för direktuppspelningsappen genom att anropa slutpunkten /api/v2/{serviceProvider}/profiles .

Scenario 1: Det finns befintliga profiler. Programmeringstjänsten kan fortsätta till förauktoriseringsfasen eller auktoriseringsfasen.

Scenario 2: Det finns inga befintliga profiler. Programmeringstjänsten kan gå vidare till nästa steg för att autentisera användaren.

Scenario 3: Det finns inga befintliga profiler. Programmeringstjänsten kan fortsätta att ge användaren tillfällig åtkomst via funktionen TempPass.

• Det här scenariot ligger utanför det här dokumentets omfång. Mer information finns i dokumentationen för Tillfälliga åtkomstflöden.

Hämta konfiguration: Programmeringstjänsten hämtar listan över tillgängliga MVPD-filer genom att anropa slutpunkten /api/v2/{serviceProvider}/configuration .

• Programmeringstjänsten kan implementera en anpassad filtreringsmekanism för att förfina listan över MVPD-program från konfigurationssvaret, så att Streaming App endast visar de avsedda leverantörerna medan andra döljs (t.ex. MVPD-program som håller på att utvecklas, testar MVPD-program, TempPass). Detta garanterar att användarna får ett välstrukturerat urval när de väljer sin tv-leverantör.

Skapa autentiseringssession: Programmeringstjänsten initierar en autentiseringssession genom att anropa slutpunkten /api/v2/{serviceProvider}/sessions.

• Programmerartjänsten måste returnera code och url till direktuppspelningsappen.

Scenario 1: Direktuppspelningsappen kan öppna en webbläsare eller webbvy och måste därför läsa in autentiseringen url.

• Användaren anger sitt användarnamn och lösenord på inloggningssidan för MVPD. När autentiseringen är klar visas en sida för slutförd omdirigering.

Scenario 2: Direktuppspelningsappen kan inte öppna en webbläsare och måste därför visa autentiseringen code. Ett separat webbprogram krävs för att uppmana användaren att ange code, konstruera autentiseringen url och öppna: /api/v2/authenticate/{serviceProvider}/{code}.

• Användaren anger sitt användarnamn och lösenord på inloggningssidan för MVPD. När autentiseringen är klar visas en sida för slutförd omdirigering.

Hämta profil för specifik kod: Programmeringstjänsten måste implementera en avsökningsmekanism med code för att kontrollera om profilen genererades och sparades genom att anropa slutpunkten /api/v2/{serviceProvider}/profiles/code/{code}.

• Programmerartjänsten måste starta avsökningsfunktionen på följande villkor:

  • Autentisering som utförs i det primära (skärm) programmet: Programmerartjänsten ska starta avsökningen när användaren kommer till den sista målsidan, efter att webbläsarkomponenten har läst in den URL som angetts för parametern redirectUrl i Sessions -slutpunktsbegäran.

  • Autentisering som utförs i ett sekundärt (skärm) program: Programmerartjänstprogrammet bör börja avfråga så snart användaren initierar autentiseringsprocessen - direkt efter att ha tagit emot Sessioner -slutpunktssvaret och visar autentiseringskoden för användaren.

• Programmerartjänsten måste stoppa avsökningsfunktionen under följande villkor:

  • Autentiseringen är klar: Användarens profilinformation har hämtats och autentiseringsstatusen har bekräftats. I nuläget behövs ingen avsökning längre.

  • Autentiseringssession och förfallodatum för kod: Autentiseringssessionen och koden förfaller, vilket anges av tidsstämpeln notAfter (t.ex. 30 minuter) i slutpunktssvaret för sessioner. Om detta inträffar måste användaren starta om autentiseringsprocessen och avsökningen med den tidigare autentiseringskoden ska stoppas omedelbart.

  • Ny autentiseringskod har genererats: Om användaren begär en ny autentiseringskod på den primära (skärm) enheten är den befintliga sessionen inte längre giltig och avsökningen med den tidigare autentiseringskoden bör stoppas omedelbart.

• Programmerartjänsten måste konfigurera avsökningsfrekvensen under följande förhållanden:

  • Autentisering som utförs i det primära (skärm) programmet: Programmeringstjänsten bör avsöka var 3-5:e sekund eller mer.

  • Autentisering som utförs i ett sekundärt (skärm) program: Programmeringstjänsten bör avsöka var 3-5:e sekund eller mer.

• Programmerartjänsten bör cachelagra delar av användarens profilinformation i en beständig lagringsplats för att undvika onödiga begäranden och förbättra användarupplevelsen.

Hämta beslut om förhandsauktorisering: Programmeringstjänsten hämtar beslut om förhandsauktorisering för en lista med resurser genom att anropa slutpunkten /api/v2/{serviceProvider}/Decision/preauthorized/{mvpd} .

• Programmeringstjänsten måste skicka listan över tillstånd och neka förauktoriseringsbeslut till Streaming App.

• Programmerartjänsten behövs inte för att lagra förauktoriseringsbeslut i beständig lagring. Vi rekommenderar dock att du cachelagrar tillståndsbeslut i minnet för att förbättra användarupplevelsen. På så sätt undviker du onödiga krav på resurser som redan har förauktoriserats, vilket minskar latensen och förbättrar prestandan.

• Programmerartjänsten kan fastställa orsaken till ett beslut om förauktorisering som nekats genom att granska felkoden och meddelandet som ingår i svaret från slutpunkten för förauktorisering av beslut. Dessa detaljer ger insikt i den specifika anledningen till att förauktoriseringsbegäran nekades, vilket kan hjälpa användaren att informera om användarupplevelsen eller utlösa nödvändig hantering i programmet. Se till att alla återförsöksmetoder som implementeras för att hämta beslut om förauktorisering inte resulterar i en oändlig slinga om beslutet om förauktorisering nekas. Överväg att begränsa antalet försök till ett rimligt antal och hantera nekanden på ett enkelt sätt genom att ge användaren tydlig feedback.

• Programmeringstjänsten kan få ett beslut om förhandsbehörighet för ett begränsat antal resurser i en enda API-begäran, vanligtvis upp till 5, på grund av villkor som anges av distributörer av videoprogrammeringstjänster. Det maximala antalet resurser kan visas och ändras efter att du har godkänt PDF-filer via Adobe Pass TVE Dashboard av en av organisationens administratörer eller av en Adobe Pass-autentiseringsrepresentant som agerar för din räkning.

Hämta auktoriseringsbeslut: Programmerartjänsten hämtar auktoriseringsbeslut för en specifik resurs som skickas av direktuppspelningsappen genom att anropa slutpunkten /api/v2/{serviceProvider}/Decision/authorized/{mvpd}.

• Programmerartjänsten behövs inte för att lagra auktoriseringsbeslut i beständig lagring.

• Programmerartjänsten kan fastställa orsaken till ett beslut om nekad auktorisering genom att granska felkoden och meddelandet som ingår i svaret från slutpunkten för auktorisering av beslut. Dessa uppgifter ger insikt i varför auktoriseringsbegäran nekades, vilket kan bidra till att informera användaren eller utlösa nödvändig hantering i Streaming App. Se till att alla återförsöksmetoder som implementeras för att hämta auktoriseringsbeslut inte resulterar i en oändlig slinga om auktoriseringsbeslutet nekas. Överväg att begränsa antalet försök till ett rimligt antal och hantera nekanden på ett enkelt sätt genom att ge användaren tydlig feedback.

• Programmeringstjänsten kan utvärdera andra affärsregler och returnera ett lämpligt auktoriseringsbeslut till Streaming App.

• Programmerartjänsten behöver inte uppdatera en medietoken som har upphört att gälla medan strömmen spelas upp. Om medietoken upphör att gälla under uppspelning bör strömmen kunna fortsätta utan avbrott. Klienten måste dock begära ett nytt auktoriseringsbeslut - och få en ny medietoken - nästa gång användaren försöker spela upp en resurs.

• Programmeringstjänsten kan få ett auktoriseringsbeslut för ett begränsat antal resurser i en enda API-begäran, vanligtvis upp till 1, på grund av villkor som anges av distributörer av videoprogrammeringstjänster.

Initiera Adobe Pass-utloggning: Programmeringstjänsten initierar utloggningsflödet enligt Streaming App-programmets begäran genom att anropa slutpunkten /api/v2/{serviceProvider}/logout/{mvpd}.

• Programmerartjänsten kan rensa all information som lagras om den autentiserade användaren.

• Programmeringstjänsten måste följa instruktionerna i attributen actionName och actionType för utloggningsslutpunktssvaret för att säkerställa att utloggningsprocessen slutförs korrekt.

  • Om attributet actionType i svaret är inställt på "interaktiv" måste programmeringstjänsten returnera attributvärdet url till direktuppspelningsappen.

    • Scenario 1: Direktuppspelningsappen kan öppna en webbläsare eller webbvy och måste därför läsa in utloggningen url.

    • Scenario 2: Direktuppspelningsappen kan inte öppna en webbläsare, och därför kan utloggningsprocessen stoppas eftersom MVPD-sessionen inte sparades i en webbläsarcache för direktuppspelningsenheten.