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. # AWS demande de service ## Quand l’utiliser Avec`AWS_SERVICE_REQUEST`, vous pouvez appeler les API de AWS service prises en charge lors de la personnalisation du manifeste. Vous pouvez actuellement appeler Elemental Inference GetMetadata pour le ciblage publicitaire contextuel. MediaTailor signe la demande avec ses propres informations d'identification de service et ajoute automatiquement les en-têtes d'authentification et de sécurité requis. Il n'est pas nécessaire de configurer les rôles IAM ni de gérer les informations d'identification. Pour une présentation guidée qui inclut les prérequis, les politiques en matière de ressources et les considérations régionales, consultez. [Intégration de l'inférence élémentaire](monetization-functions-elemental-inference-integration.md) ## Champs de configuration Une `AWS_SERVICE_REQUEST` fonction comporte les champs suivants : + **Runtime ** (obligatoire) : langage d'expression. Réglez ce paramètre sur`JSONATA`. + **TargetService**(obligatoire) — Le AWS service cible. Actuellement, seul `elemental-inference` est pris en charge. + **TargetRegion**(obligatoire) — La AWS région du service cible. Vous pouvez utiliser une valeur statique (par exemple`us-west-2`) ou une JSONata expression pour la résolution dynamique (par exemple,`{%inference.region%}`). + **MethodType**(obligatoire) — Méthode HTTP. Les valeurs prises en charge sont `GET` et`POST`, selon l'API du service cible. + **URL ** (obligatoire) : point de terminaison HTTPS de l'API du AWS service. Il doit s'agir d'une URL de point de AWS terminaison valide. Vous pouvez utiliser une JSONata expression pour créer l'URL de manière dynamique. + **En-têtes ** (facultatif) : en-têtes HTTP supplémentaires à inclure dans la demande. Pour les restrictions relatives aux en-têtes, consultez[Modèle de sécurité](#monetization-functions-types-aws-service-request-security). + **Corps ** (conditionnel) — Le corps de la demande. Obligatoire quand `MethodType` c'est le `POST` cas Vous pouvez utiliser une JSONata expression pour créer le corps de manière dynamique à partir de l'état de session. + **RequestTimeoutMilliseconds**(obligatoire) — Combien de temps faut-il attendre pour obtenir une réponse ? + **Sortie ** (facultatif) — Définit les valeurs à produire une fois l'appel terminé. Chaque entrée associe une clé de sortie à une expression qui peut faire référence à l'`response`objet. Les expressions de sortie peuvent faire référence au même `response` objet décrit dans[Champs de réponse](monetization-functions-types-http-request.md#monetization-functions-types-http-request-response). ## Modèle de sécurité MediaTailor signe la demande sortante en utilisant son propre rôle de service. Il n'est pas nécessaire de créer ou de configurer des rôles IAM MediaTailor pour appeler le service cible. La AWS ressource cible doit disposer d'une politique de ressources qui accorde au MediaTailor service principal un accès assorti `aws:SourceAccount` de `aws:SourceArn` conditions. Ces conditions fournissent une protection d'accès interservices en garantissant que MediaTailor vous ne pouvez accéder à la ressource que pour le compte de votre compte et des configurations de lecture spécifiques. Pour des exemples complets de politiques relatives aux ressources, consultez[Autorisez MediaTailor l'accès à votre flux d'inférence élémentaire](monetization-functions-elemental-inference-integration.md#monetization-functions-elemental-inference-integration-access). **Restrictions relatives aux en-têtes : ** tous les en-têtes comportant un `X-Amz-` préfixe sont réservés. MediaTailor remplace ces en-têtes par les valeurs d'authentification et de protection d'accès interservices requises. N'incluez pas d'`X-Amz-`en-têtes dans votre configuration. ## Comment la demande est traitée MediaTailor traite et `AWS_SERVICE_REQUEST` fonctionne en trois étapes : 1. **Génère la demande ** : MediaTailor évalue les `Body` expressions `Url``Headers`, et par rapport à l'état actuel de la session. L'URL doit être un point de terminaison valide pour le service spécifié. 1. **Signez la demande ** : MediaTailor authentifie la demande à l'aide de ses propres informations d'identification de service pour le `TargetService` et`TargetRegion`. 1. **Traiter la réponse ** — Une fois l'appel terminé, MediaTailor évalue les expressions du bloc Output. Ces expressions peuvent faire référence à la fois à l'état de session d'origine et à l'`response`objet renvoyé par l'appel. ## Champs de réponse Une fois l'appel terminé, vous pouvez référencer les champs suivants dans vos expressions de sortie : | Champ | Type | Description | | --- | --- | --- | | response.body | Objet ou tableau | Le corps de la réponse est analysé au format JSON. Défini sur null si le corps dépasse 20 000 caractères ou s'il ne s'agit pas d'un JSON valide. | | response.statusCode | Entier | Code d'état HTTP renvoyé par le AWS service. Réglez null sur en cas de défaillance du réseau. | | response.text | Chaîne | Le corps brut de la réponse sous forme de chaîne, tronqué à 20 000 caractères. Réglez "Internal Error" sur en cas de défaillance du réseau. | **Important** La taille de réponse maximale est de 20 000 caractères. Les réponses qui dépassent cette limite `response.body` sont définies sur`null`. ## Gestion des erreurs Ce qui suit décrit la façon dont MediaTailor les erreurs sont gérées pour `AWS_SERVICE_REQUEST` les fonctions : + Si le délai de la demande expire (dépasse`RequestTimeoutMilliseconds`), `response.statusCode` est `null` et `response.body` est`null`. Vos expressions de sortie s'exécutent toujours. + Si le service cible renvoie une erreur 4xx ou 5xx, il contient le code d'état HTTP et `response.statusCode` `response.body` contient la réponse à l'erreur (s'il s'agit d'un JSON valide et de moins de 20 000 caractères). + Si le corps de la réponse dépasse 20 000 caractères, `response.body` c'est `null` même si la réponse a réussi. À utiliser `response.text` pour le contenu tronqué brut. + Lorsqu'une fonction échoue ou produit une sortie vide, MediaTailor procède à l'insertion de l'annonce en utilisant les valeurs disponibles sans la contribution de la fonction. La pause publicitaire n'est pas bloquée. **Astuce** Vérifiez `response.statusCode` toujours vos expressions de sortie pour gérer les erreurs correctement. ## Exemple : inférence élémentaire GetMetadata La fonction suivante appelle Elemental Inference `GetMetadata` pour récupérer les métadonnées contextuelles de la fenêtre de contenu autour de la pause publicitaire en cours. Le `Body` champ utilise une JSONata expression pour construire dynamiquement la requête JSON à partir de `inference.*` variables. Il extrait les catégories de IAB taxonomie et les signaux de sécurité des GARM marques, puis les stocke en tant que paramètres du lecteur à utiliser dans les requêtes ADS. ``` { "FunctionId": "eiContextualMetadata", "FunctionType": "AWS_SERVICE_REQUEST", "AwsServiceRequestConfiguration": { "Runtime": "JSONATA", "TargetService": "elemental-inference", "TargetRegion": "{%inference.region%}", "MethodType": "POST", "Url": "{%inference.dataEndpoint & '/v1/feed/' & inference.feedId & '/input/0/metadata'%}", "Headers": { "Content-Type": "application/json" }, "Body": "{%'{\"outputName\": \"my-contextual-output\", \"timeSpecification\": {\"ptsBased\": {\"startPts\": ' & $string(($exists(inference.previousBreakEndPts) and inference.previousBreakEndPts > inference.pts - 30 * inference.timescale ? inference.previousBreakEndPts : inference.pts - 30 * inference.timescale)) & ', \"endPts\": ' & $string(inference.pts + 1) & ', \"timescale\": ' & $string(inference.timescale) & '}}, \"parameters\": {\"contextualMetadata\": {}}}' %}", "RequestTimeoutMilliseconds": 2000, "Output": { "player_params.iabCategories": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.iabTaxonomy.categories.uniqueId), ',') : ''%}", "player_params.garmExcluded": "{%response.statusCode = 200 ? $join($distinct(response.body.items.metadata.contextualMetadata.garm.suitability.categories[flagged = true].category), ',') : ''%}" } } } ``` Au moment de l'exécution, `Body` l'expression produit une charge utile JSON comme suit : ``` { "outputName": "my-contextual-output", "timeSpecification": { "ptsBased": { "startPts": 162000000, "endPts": 163600001, "timescale": 90000 } }, "parameters": { "contextualMetadata": {} } } ``` La `startPts` valeur est la plus tardive des deux valeurs suivantes : la fin de la dernière pause publicitaire (`inference.previousBreakEndPts`) ou 30 secondes avant la pause en cours. La `endPts` valeur est le PTS de la pause en cours plus un. **Note** Remplacez-le `my-contextual-output` par le nom de la sortie de métadonnées contextuelles de votre flux Elemental Inference. **Note** MediaTailor inclut automatiquement l'`x-amzn-elemental-inference-skip-poll`en-tête des requêtes adressées à Elemental Inference. Cela garantit des réponses à faible latence adaptées au timing des pauses publicitaires. Pour un guide de configuration complet comprenant les prérequis et les politiques en matière de ressources, consultez[Intégration de l'inférence élémentaire](monetization-functions-elemental-inference-integration.md).