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

Kommunizieren Sie mit dem Adobe Pass-Service im Namen der Streaming-App.

Erfassen und übergeben Sie eine eindeutige Gerätekennung für das Streaming-Gerät, wie vom AP-Device-Identifier-Header benötigt.

Erfassen und übergeben Sie genaue Streaming-Geräteinformationen, einschließlich des Quell-Ports und gerätespezifischer Details, wie vom X-Device-Info-Header benötigt.

Erfassen und übergeben Sie die IP-Adresse des Streaming-Geräts gemäß der Kopfzeile „X-Forwarded-For“.

Speichern Sie Parameter wie Geräte-ID, Client-ID und Client-Geheimnis sicher in der Streaming-App oder im Programmierdienst.

Formatieren und senden Sie Daten in Übereinstimmung mit MVPDs und integrierten Apps, einschließlich Geräte-IP, Quell-Port, gerätespezifischen Informationen, MRSS und optionalen Kennungen wie ECID.

Verwalten und verwalten Sie Zertifikate, die mit Adobe für die verschlüsselte Übertragung von Benutzermetadaten freigegeben sind.

Achten Sie beim Caching auf die Gültigkeit des Authentifizierungsprofils und der Autorisierungsentscheidung, um sicherzustellen, dass der Authentifizierungs- und Autorisierungsstatus bei der Benachrichtigung ungültig gemacht wird.

Rückgabe von Autorisierungsentscheidungen und relevanten Anweisungen an die Streaming-App.

Der Adobe Pass-Service wird in mehreren geografisch verteilten Rechenzentren in den USA eingesetzt, um die Leistung zu optimieren und die Latenz zu minimieren.

• Der Programmierer-Service sollte eine ähnliche Infrastrukturstrategie anwenden, um Antwortzeiten mit geringer Latenz von Adobe Pass sicherzustellen.

Der Programmierer muss den öffentlichen IP-Bereich seiner Produktionsumgebung bereitstellen.

• Diese IPs werden einer Zulassungsliste in der Adobe Pass-Infrastruktur hinzugefügt.

Der Programmierdienst muss die DNS-Zwischenspeicherung auf maximal 30 Sekunden beschränken, um ein dynamisches Rerouting zu ermöglichen, falls Adobe Traffic umleiten muss, weil ein Rechenzentrum nicht verfügbar ist.

Sie muss vor der Bereitstellung in der Produktion das Testen von Versionen ermöglichen.

Sie sollte operativ ähnlich wie die Produktion bleiben und realistische Tests ermöglichen.

Idealerweise sollte die Staging-Umgebung mit Adobe Pass-Testumgebungen verbunden sein, um:

• Ermöglichen Sie Programmierern, mit der Adobe-Infrastruktur zu testen.

• Aktivieren Sie Adobe, um bei Bedarf Tests und Fehlerbehebung zu unterstützen.

Client-Anmeldeinformationen abrufen: Der Programmierer-Service ruft Client-Anmeldeinformationen ab, indem er den Endpunkt /o/client/register aufruft.

• Der Programmierdienst oder die Programmieranwendung müssen die Client-Anmeldeinformationen speichern und sie unbegrenzt verwenden, wenn ein Zugriffstoken abgerufen werden muss.

Zugriffs-Token abrufen: Der Programmierer-Service ruft das Zugriffs-Token ab, indem er den Endpunkt /o/client/token aufruft.

• Der Programmierdienst oder die Programmieranwendung müssen das Zugriffstoken speichern und verwenden, bis es abläuft. Dann müssen Sie es verwerfen und ein neues abrufen.

Profile abrufen: Der Programmierdienst überprüft im Auftrag der Streaming-App vorhandene Profile, indem er den Endpunkt /api/v2/{serviceProvider}/profiles aufruft.

Szenario 1: Profile vorhanden sind, kann der Programmierer-Service mit der Phase Vorabautorisierung oder Autorisierung).

Szenario 2: Es sind keine vorhandenen Profile vorhanden. Der Programmierer-Service kann mit dem nächsten Schritt fortfahren, um den zu authentifizieren.

Szenario 3: Es sind keine vorhandenen Profile vorhanden. Der Programmierer-Service kann dem Benutzer über die Funktion TempPass“ temporären Zugriff.

• Dieses Szenario würde den Rahmen dieses Dokuments sprengen. Weitere Informationen finden Sie in der Dokumentation Temporärer".

Konfiguration abrufen: Der Programmierdienst ruft die Liste der verfügbaren MVPDs ab, indem er den Endpunkt /api/v2/{serviceProvider}/configuration aufruft.

• Der Programmierer-Service kann einen benutzerdefinierten Filtermechanismus implementieren, um die Liste der MVPDs aus der Konfigurationsantwort so zu verfeinern, dass die Streaming-App nur die vorgesehenen Anbieter anzeigt, während andere ausgeblendet werden (z. B. MVPDs in Entwicklung, MVPDs testen, TempPass). Dadurch wird sichergestellt, dass Benutzenden bei der Auswahl ihres TV-Anbieters eine kuratierte Auswahl angezeigt wird.

Authentifizierungssitzung erstellen: Der Programmierdienst initiiert eine Authentifizierungssitzung, indem er den Endpunkt /api/v2/{serviceProvider}/sessions aufruft.

• Der Programmierdienst muss die code und die url an die Streaming-App zurückgeben.

Szenario 1: Die Streaming-App kann einen Browser oder eine Webansicht öffnen, daher muss die url geladen werden.

• Der Benutzer gibt seinen Benutzernamen und sein Kennwort auf der Anmeldeseite von MVPD ein. Nach erfolgreicher Authentifizierung zeigt die endgültige Umleitung eine Erfolgsseite an.

Szenario 2: Die Streaming-App kann keinen Browser öffnen, daher muss die code angezeigt werden. Eine separate Web-Anwendung ist erforderlich, um den Benutzer zur Eingabe der code aufzufordern, die url zu erstellen und zu öffnen: /api/v2/Authenticate/{serviceProvider}/{code}.

• Der Benutzer gibt seinen Benutzernamen und sein Kennwort auf der Anmeldeseite von MVPD ein. Nach erfolgreicher Authentifizierung zeigt die endgültige Umleitung eine Erfolgsseite an.

Profil für bestimmten Code abrufen: Der Programmierer-Service muss einen Abrufmechanismus mithilfe des code implementieren, um zu überprüfen, ob das Profil erfolgreich generiert und gespeichert wurde, indem der /api/v2/{serviceProvider}/profiles/code/{code}-Endpunkt aufgerufen wird.

• Der Programmierdienst muss Abrufmechanismus folgenden Bedingungen starten:

  • Authentifizierung in der primären (Bildschirm-)Anwendung: Der Programmierdienst sollte die Abfrage starten, wenn der Benutzer die endgültige Zielseite erreicht, nachdem die Browser-Komponente die für den redirectUrl Parameter in der Endpunktanforderung Sitzungen angegebene URL geladen hat.

  • Authentifizierung in einer sekundären (Bildschirm-)Anwendung: Die Programmierer-Service-Anwendung sollte den Abruf starten, sobald der Benutzer den Authentifizierungsprozess einleitet - direkt nach Erhalt der Sessions-Endpunktantwort und Anzeige des Authentifizierungs-Codes für den Benutzer.

• Der Programmierdienst muss Abfrage- unter folgenden Bedingungen stoppen:

  • Erfolgreiche Authentifizierung: Die Profilinformationen des Benutzers wurden erfolgreich abgerufen und bestätigen seinen Authentifizierungsstatus. Zu diesem Zeitpunkt ist keine Abfrage mehr erforderlich.

  • Authentifizierungssitzung und Code-Ablauf: Die Authentifizierungssitzung und der Code laufen ab, wie durch den notAfter Zeitstempel (z. B. 30 Minuten) in der Endpunktantwort Sitzungen angegeben. In diesem Fall muss der Benutzer den Authentifizierungsprozess neu starten, und das Abrufen mit dem vorherigen Authentifizierungs-Code sollte sofort gestoppt werden.

  • Generierter neuer Authentifizierungs-Code: Wenn der Benutzer einen neuen Authentifizierungs-Code auf dem Primärgerät (Bildschirm) anfordert, ist die vorhandene Sitzung nicht mehr gültig und das Abrufen mit dem vorherigen Authentifizierungs-Code sollte sofort gestoppt werden.

• Der Programmierdienst muss Abrufintervall konfigurieren unter folgenden Bedingungen:

  • Authentifizierung innerhalb der primären (Bildschirm-)Anwendung: Der Programmierer-Service sollte alle 3-5 Sekunden oder länger abfragen.

  • Authentifizierung in einer sekundären (Bildschirm-)Anwendung: Der Programmierer-Service sollte alle 3-5 Sekunden oder länger abfragen.

• Der Programmierdienst sollte Teile der Profilinformationen des Benutzers in einem beständigen Speicher zwischenspeichern, um unnötige Anfragen zu vermeiden und das Benutzererlebnis zu verbessern.

Vorabautorisierungsentscheidungen abrufen: Der Programmierer-Service ruft Vorabautorisierungsentscheidungen für eine Liste von Ressourcen ab, indem er den Endpunkt /api/v2/{serviceProvider}/decisions/preauthorize/{mvpd} aufruft.

• Der Programmierer-Service muss der Streaming-App die Liste der Genehmigungsentscheidungen übergeben und Vorabautorisierungsentscheidungen ablehnen.

• Der Programmierdienst ist nicht erforderlich, um Entscheidungen vor Autorisierung in einem persistenten Speicher zu speichern. Es wird jedoch empfohlen, Zulassungsentscheidungen im Speicher zwischenzuspeichern, um das Benutzererlebnis zu verbessern. Dadurch werden unnötige Aufrufe von Ressourcen vermieden, die bereits vorab autorisiert wurden, die Latenz verringert und die Leistung verbessert.

• Der Programmierer-Service kann den Grund für eine abgelehnte Vorautorisierungsentscheidung ermitteln, indem er den Fehlercode und die Nachricht) überprüft die in der Antwort vom Endpunkt Decisions Preauthorize enthalten sind. Diese Details bieten Einblicke in den spezifischen Grund, aus dem die Vorabautorisierungsanfrage abgelehnt wurde, und helfen, das Benutzererlebnis oder den Trigger über die erforderliche Handhabung in der Anwendung zu informieren. Stellen Sie sicher, dass ein Wiederholungsmechanismus, der zum Abrufen von Entscheidungen vor der Autorisierung implementiert ist, nicht zu einer Endlosschleife führt, wenn die Entscheidung vor der Autorisierung abgelehnt wird. Erwägen Sie, weitere Zustellversuche auf eine angemessene Anzahl zu beschränken und Ablehnungen elegant zu handhaben, indem Sie dem Benutzer klares Feedback senden.

• Der Programmierer-Service kann in einer einzigen API-Anfrage eine Vorabautorisierungsentscheidung für eine begrenzte Anzahl von Ressourcen erhalten, in der Regel bis zu 5, aufgrund von Bedingungen, die von MVPDs auferlegt werden. Diese maximale Anzahl von Ressourcen kann angezeigt und geändert werden, nachdem eine Vereinbarung mit MVPDs über das Adobe Pass TVE-Dashboard von einem Ihrer Organisationsadministratoren oder einem in Ihrem Namen handelnden Adobe Pass-Authentifizierungsmitarbeiter getroffen wurde.

Autorisierungsentscheidung abrufen: Der Programmierer-Service ruft die Autorisierungsentscheidung für eine bestimmte Ressource ab, die von der Streaming-App übergeben wird, indem er den Endpunkt /api/v2/{serviceProvider}/decision/authorize/{mvpd} aufruft.

• Der Programmierdienst ist nicht erforderlich, um Autorisierungsentscheidungen in einem persistenten Speicher zu speichern.

• Der Programmierer-Service kann den Grund für eine Entscheidung bezüglich der verweigerten Autorisierung ermitteln, indem er den Fehlercode und die Meldung) prüft die in der Antwort vom Endpunkt Decisions Authorize enthalten sind. Diese Details geben insight den spezifischen Grund an, aus dem die Autorisierungsanfrage abgelehnt wurde. So kann das Benutzererlebnis oder der Trigger über die erforderliche Verarbeitung in der Streaming-App informiert werden. Stellen Sie sicher, dass ein zum Abrufen von Autorisierungsentscheidungen implementierter Wiederholungsmechanismus nicht zu einer Endlosschleife führt, wenn die Autorisierungsentscheidung abgelehnt wird. Erwägen Sie, weitere Zustellversuche auf eine angemessene Anzahl zu beschränken und Ablehnungen elegant zu handhaben, indem Sie dem Benutzer klares Feedback senden.

• Der Programmierer-Service kann andere Geschäftsregeln bewerten und eine geeignete Autorisierungsentscheidung an die Streaming-App zurückgeben.

• Der Programmierer-Service ist nicht erforderlich, um ein abgelaufenes Medien-Token zu aktualisieren, während der Stream aktiv wiedergegeben wird. Wenn das Medien-Token während der Wiedergabe abläuft, sollte der Stream ununterbrochen fortgesetzt werden können. Der Client muss jedoch beim nächsten Versuch, eine Ressource abzuspielen, eine neue Autorisierungsentscheidung anfordern und ein neues Medien-Token abrufen.

• Der Programmierer-Service kann in einer einzelnen API-Anfrage, in der Regel bis zu 1, eine Autorisierungsentscheidung für eine begrenzte Anzahl von Ressourcen erhalten, da die MVPDs Bedingungen festlegen.

Adobe Pass-Abmeldung initiieren: Der Programmierer-Service initiiert den Abmeldefluss wie von der Streaming-App angefordert, indem er den Endpunkt /api/v2/{serviceProvider}/logout/{mvpd} aufruft.

• Der Programmierdienst kann alle gespeicherten Informationen über den authentifizierten Benutzer bereinigen.

• Der Programmierdienst muss den Anweisungen in den actionName- und actionType-Attributen der Antwort des Abmeldeendpunkts folgen, um sicherzustellen, dass der Abmeldevorgang korrekt abgeschlossen wird.

  • Wenn das actionType Attribut in der Antwort auf „interaktiv“ festgelegt ist, muss der Programmierer-Service den Wert des url Attributs an die Streaming-App zurückgeben.

    • Szenario 1: Die Streaming-App kann einen Browser oder eine Webansicht öffnen, daher muss die Abmelde-url geladen werden.

    • Szenario 2: Die Streaming-App kann keinen Browser öffnen. Daher kann der Abmeldevorgang angehalten werden, da die MVPD-Sitzung nicht in einem Browser-Cache für Streaming-Geräte gespeichert wurde.