View a markdown version of this page

Guide de démarrage rapide des fonctions - AWS Elemental MediaTailor
Conditions préalablesÉtape 1 : Création d’une fonctionÉtape 2 : associer la fonction à une configuration de lectureÉtape 3 : démarrer une session et vérifier que la fonction a été exécutéeQue se passe-t-il dans les coulissesSujets suggérés

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Guide de démarrage rapide des fonctions

Ce guide vous explique comment créer votre première fonction, l'associer à une configuration de lecture et vérifier qu'elle s'est exécutée. À la fin, vous disposerez d'une fonction fonctionnelle qui classifie le type d'appareil de chaque spectateur (ctv,mobile, oudesktop) et le stocke en tant que paramètre du joueur disponible dans chaque requête ADS.

Conditions préalables

Avant de commencer, assurez-vous que vous disposez d'une configuration MediaTailor de lecture existante. Si vous n'en avez pas, veuillez consulter Commencer avec MediaTailor.

Étape 1 : Création d’une fonction

Au cours de cette étape, vous créez une fonction qui classe le type d'appareil du spectateur en fonction de la chaîne de l'agent utilisateur et enregistre le résultat dans les paramètres du lecteur. La fonction utilise un type de sortie personnalisé (aucun appel d'API externe) avec une Référence d'expression JSonata expression pour évaluer l'agent utilisateur.

  1. Ouvrez la MediaTailor console à l'adresse https://console.aws.amazon.com/mediatailor/.

  2. Dans le volet de navigation, choisissez Fonctions.

  3. Choisissez Créer une fonction.

  4. Dans le mode de l'assistant de création, sélectionnez Créer à partir de zéro, puis choisissez Continuer.

  5. Sous Type de fonction, sélectionnez la vignette de sortie personnalisée.

  6. Sous Détails de la fonction, entrez les informations suivantes :

    • Identifiant de la fonction : myFirstFunction

    • Description : Classify device type from user agent

  7. Sous Configuration de sortie personnalisée, dans la section Sortie, ajoutez une ligne :

    • Clé : player_params.deviceType

    • Value (Valeur) : {% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}

  8. Choisissez Créer une fonction.

Une notification de réussite confirme que la fonction a été créée et vous êtes redirigé vers la page de détails de la fonction.

La configuration de fonction qui en résulte est la suivante :

{
    "FunctionId": "myFirstFunction",
    "FunctionType": "CUSTOM_OUTPUT",
    "Description": "Classify device type from user agent",
    "CustomOutputConfiguration": {
        "Runtime": "JSONATA",
        "Output": {
            "player_params.deviceType": "{% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}"
        }
    }
}

Étape 2 : associer la fonction à une configuration de lecture

Associez la fonction à un crochet du cycle de vie de votre configuration de lecture. Le mappage indique MediaTailor quand exécuter la fonction.

  1. Dans le volet de navigation, sélectionnez Configurations.

  2. Choisissez la configuration de lecture que vous souhaitez mettre à jour.

  3. Choisissez Modifier.

  4. Développez la section Configuration des fonctions.

  5. Pour le hook d'initialisation de session, sélectionnez-le dans le myFirstFunction menu déroulant.

  6. Choisissez Enregistrer.

Cela se rattache myFirstFunction au crochet du INITIALISATION AVANT LA SESSION cycle de vie. Le mappage des fonctions qui en résulte est le suivant :

{
    "FunctionMapping": {
        "PRE_SESSION_INITIALIZATION": "myFirstFunction"
    }
}

MediaTailor exécute la fonction une fois au début de chaque nouvelle session sur cette configuration de lecture.

Étape 3 : démarrer une session et vérifier que la fonction a été exécutée

Démarrez une nouvelle session de lecture pour déclencher la fonction. Envoyez une demande d'initialisation de session au point de terminaison d'initialisation de session de votre configuration de lecture.

MediaTailor publie automatiquement CloudWatch des métriques pour chaque exécution de fonction, sans inscription. Après avoir démarré une session, vérifiez les métriques suivantes dans l'espace de AWS/MediaTailor noms pour confirmer que votre fonction a été exécutée :

  • PreSessionInitHook.Invocations— Confirme que l'hameçon a été activé.

  • PreSessionInitHook.Errors— Doit être égal à 0 en cas de réussite de la fonction.

  • Function.Invocations— Confirme la fonction individuelle exécutée. Cette métrique inclut FunctionIdFunctionType, et les HookType dimensions afin que vous puissiez filtrer myFirstFunction spécifiquement.

Si la fonction échoue, MediaTailor envoie les événements du journal d'erreurs dans Manifest Logs par défaut (aucune configuration n'est requise) :

  • PRE_SESSION_INIT_HOOK_ERROR— Hook-level échec avec errorType etcause.

  • PRE_SESSION_INIT_FUNCTION_ERROR— Function-level échec avec les détails spécifiques functionId et les détails de l'erreur.

L'exemple suivant montre un PRE_SESSION_INIT_FUNCTION_ERROR événement lié à une erreur de syntaxe dans l'expression de la fonction :

{
    "eventTimestamp": "2024-01-01T12:00:00.076000000Z",
    "eventType": "PRE_SESSION_INIT_FUNCTION_ERROR",
    "eventDescription": "Function execution failed",
    "awsAccountId": "123456789012",
    "originId": "my-config",
    "sessionId": "session-123",
    "requestId": "req-abc",
    "eventId": "5dc6f040-0f72-4e8c-a64e-25eeef62708c",
    "functionId": "myFirstFunction",
    "functionType": "CUSTOM_OUTPUT",
    "executionTimeMs": 2,
    "errorType": "SYNTAX_ERROR",
    "cause": "Expected \")\" before end of expression",
    "input": {}
}

Utilisez le eventId champ pour corréler les événements d'erreur de type hook et function pour une même exécution. Le errorType champ indique la classe d'échec. Consultez Résolution des problèmes et surveillance la liste complète des types d'erreurs et des correctifs.

Note

Pour une journalisation détaillée des réussites, inscrivez-vous à votre configuration Manifest Log PRE_SESSION_INIT_HOOK_SUMMARY et enregistrez les PRE_SESSION_INIT_FUNCTION_COMPLETED événements dans cette configuration. Les événements récapitulatifs indiquent le résultat du hook pour chaque exécution. Les événements terminés affichent les request/response informations relatives à l'entrée, à la sortie et au protocole HTTP de chaque fonction. Ils sont désactivés par défaut afin de minimiser les coûts de journalisation. Pour de plus amples informations, veuillez consulter Résolution des problèmes et surveillance.

Que se passe-t-il dans les coulisses

Voici le flux de requêtes complet pour la fonction que vous venez de créer :

  1. Le joueur lance une session avec MediaTailor.

  2. MediaTailor déclenche le PRE_SESSION_INITIALIZATION cycle de vie et s'exécutemyFirstFunction.

  3. La fonction évalue le session.user_agent champ et écrit ctvmobile, ou desktop dans. player_params.deviceType

  4. MediaTailor crée la session et renvoie le manifeste au joueur.

  5. Le joueur rencontre une interruption publicitaire pendant la lecture.

  6. MediaTailor déclenche le hook PRE_ADS_REQUEST du cycle de vie, puis construit la demande ADS. Comme il deviceType est stocké dans les paramètres du joueur, il peut être inclus dans l'URL de demande ADS par le biais d'une substitution dynamique de variables.

  7. L'ADS utilise le type d'appareil pour renvoyer des créations publicitaires ciblées.

  8. MediaTailor insère les publicités dans le manifeste et le renvoie au joueur.

Si la fonction échoue pour une raison quelconque, MediaTailor la sortie est supprimée et procède comme si aucune fonction n'était attachée. Le spectateur voit toujours des publicités, mais sans le ciblage par type d'appareil.

Sujets suggérés

Une fonction fonctionnelle est désormais associée à une configuration de lecture. À partir d'ici :