Passer au contenu principal
Metronome fournit des kits de développement logiciel (SDK) puissants conçus pour intégrer de manière transparente les API de facturation Metronome dans vos applications. Les SDK pour Python, Go, Ruby et Node.js offrent aux développeurs des options flexibles pour implémenter les capacités de Metronome sur différentes plateformes et environnements. Cette page parcourt un système de facturation basé sur l’utilisation basique mais puissant en Python, Node, Ruby ou Golang :
  1. Installez et configurez le SDK Metronome.
  2. Envoyez des événements d’utilisation à Metronome, posant les fondations de la facturation basée sur la consommation.
  3. Créez une métrique facturable pour définir comment Metronome doit agréger et mesurer l’utilisation.
  4. Créez un client dans le système et associez-le aux événements d’utilisation.
  5. Configurez la tarification et le packaging de votre produit.
  6. Créez un contrat pour le client, permettant la génération automatique de factures basée sur leur utilisation.

​
Fonctionnalités du SDK

Chaque dépôt GitHub de SDK contient une documentation détaillée, des exemples et des ressources pour vous aider à tirer le meilleur parti de Metronome dans vos applications : Les fonctionnalités principales du SDK comprennent :
  • Le typage fort des points de terminaison et objets Metronome améliore la productivité des développeurs avec une meilleure autocomplétion et un meilleur support IDE pour les objets Metronome.
  • Le support de la pagination simplifie le processus de récupération et de gestion des données paginées des services Metronome.
  • Le support automatique des réessais réessaie par défaut chaque requête en cas d’échec jusqu’à trois fois. Vous pouvez le configurer à n’importe quel nombre de réessais. Utilisez ceci pour gérer automatiquement les erreurs transitoires et les problèmes réseau sans avoir besoin d’implémenter une logique de réessai.
Bien que ce guide couvre les fondamentaux, Metronome offre bien plus de fonctionnalités pour modéliser différents modèles d’affaires. Consultez le dépôt du SDK pour voir ce qui est possible.

​
1. Installer et configurer le SDK

Installez et configurez d’abord le SDK dans votre environnement : 
pip install --pre metronome-sdk
Ensuite, configurez le SDK en passant une clé d’API valide comme jeton bearer d’autorisation. Par défaut, le SDK recherche la clé d’API dans la variable d’environnement METRONOME_BEARER_TOKEN. Dans cet exemple, elle sera passée comme argument au constructeur à la place. 
from metronome import Metronome

client = Metronome(
  # Defaults to os.environ.get("METRONOME_BEARER_TOKEN") if omitted
  bearer_token="My bearer token",
)

​
2. Envoyer des événements d’utilisation

Le modèle de facturation basé sur l’utilisation s’appuie sur les données d’utilisation capturées des utilisateurs sur votre plateforme. Metronome accepte des charges utiles d’utilisation de tous formats via le point de terminaison /ingest. Utilisez le SDK pour envoyer des données à Metronome : 
response = client.v1.usage.ingest(
  usage=[
    {
      "transaction_id": "9995a70e-a2c5-4904-b96d-70de446f420e",
      "timestamp": "2024-08-01T00:00:00Z",
      "customer_id": "team@example.com",
      "event_type": "language_model",
      "properties": {
        "model": "langModel4",
        "user_id": "johndoe",
        "tokens": 1000000
      }
    }
  ]
)
Les propriétés utilisées dans cet exemple comprennent :
  • usage, vous permet de passer plusieurs charges utiles d’événements dans une requête. Metronome prend en charge le passage de jusqu’à 100 événements dans une seule requête.
  • transaction_id, fournit à Metronome la clé d’idempotence unique pour l’événement. Metronome déduplique en fonction de cet ID, vous permettant d’envoyer des événements potentiellement plusieurs fois sans vous soucier de facturer deux fois vos clients.
  • timestamp, l’heure à laquelle l’événement s’est produit. Envoyez des événements avec n’importe quel horodatage jusqu’à 34 jours dans le passé.
  • customer_id, l’ID du client dans Metronome ou tout autre identifiant client que vous voulez définir. Par exemple, l’e-mail du client ou l’ID interne du client dans votre plateforme. Les étapes ultérieures montrent comment définir ces identifiants personnalisés pour vos clients dans Metronome.
  • event_type, une chaîne arbitraire que vous pouvez définir dans la requête.
  • properties, un ensemble arbitraire de données à inclure dans la charge utile pour la mesure et le regroupement dans Metronome.
Le succès avec Metronome dépend des données que vous fournissez, il est donc important de bien concevoir les événements d’utilisation. Pour voir tous les événements envoyés à Metronome, allez dans l’onglet Événements dans l’application Metronome. Pour l’événement envoyé dans l’exemple, il est entré avec succès dans le système Metronome. Mais, il n’a pas encore été apparié avec une métrique pour commencer la mesure ni avec un client dans le système.
Voir un événement

​
3. Créer une métrique facturable

Une métrique facturable décrit une agrégation par client sur un sous-ensemble d’événements d’utilisation. En configurant une métrique facturable, vous indiquez à Metronome comment faire correspondre les événements d’utilisation aux produits que vous facturez. Voici un exemple de configuration de métrique facturable qui correspond à l’événement d’utilisation envoyé dans l’exemple précédent : 
response = client.v1.billable_metrics.create(
  name="langModel4",
  event_type_filter={
    "in_values": [
      "language_model"
    ]
  },
  property_filters=[
    {
      "name": "model",
      "exists": True,
      "in_values": [
        "langModel4"
      ]
    },
    {
      "name": "user_id",
      "exists": True
    },
    {
      "name": "tokens",
      "exists": True
    }
  ],
  aggregation_key="tokens",
  aggregation_type="SUM",
  group_keys=[
    ["user_id"]
  ]
)
  
billable_metric_id = response.data.id
Les propriétés utilisées dans le code comprennent :
  • name, le nom à donner à votre métrique facturable.
  • event_type_filter, l’ensemble de valeurs comparées au champ event_type dans les événements d’utilisation. Omettez ceci si vous voulez correspondre à tous les types d’événements.
  • property_filters, l’ensemble des propriétés que vous vous attendez à trouver dans la charge utile d’utilisation. Si vous marquez une propriété comme exists=True dans la définition de la métrique facturable et que la propriété n’est pas trouvée dans la charge utile, la métrique facturable ne correspondra pas à l’événement.
  • aggregation_key, utilisée pour définir la propriété avec la valeur pertinente sur laquelle agréger.
  • aggregation_type, utilisée pour indiquer à Metronome comment agréger les valeurs spécifiées par l’aggregation_key à mesure qu’elles entrent dans le système. Les opérations prises en charge sont SUM, COUNT et MAX.
  • group_keys, utilisées pour définir des propriétés afin de séparer les données d’utilisation dans différents seaux, similaire à une clause group by en SQL. L’exemple ci-dessus a défini user_id comme clé de groupe, vous pouvez donc afficher la facture séparée par la quantité de tokens consommée par chaque utilisateur.
Métrique facturable
Notez que les métriques facturables ne font correspondre que les événements d’utilisation envoyés après la création de la métrique facturable. Maintenant que vous avez créé la métrique, envoyez un autre événement d’utilisation pour vous assurer qu’il correspond comme prévu : 
response = client.v1.usage.ingest(
  usage=[
    {
      "transaction_id": "7e28f511-d66c-4517-91ef-a92c108e56de",
      "timestamp": "2024-08-01T00:00:00Z",
      "customer_id": "team@example.com",
      "event_type": "language_model",
      "properties": {
        "model": "langModel4",
        "user_id": "johndoe",
        "tokens": 1000000
      }
    }
  ]
)
Le nouvel événement d’utilisation correspond à la métrique facturable définie.
Métrique facturable avec un événement d'utilisation

​
4. Créer un client

Les événements d’utilisation impactent la facturation des clients, donc la prochaine étape est de créer un client dans Metronome. Utilisez le SDK pour créer un client, similaire à cet exemple : 
response = client.v1.customers.create(
  name="Example Customer",
  ingest_aliases=[
    "team@example.com"
  ]
)
  
metronome_customer_id = response.data.id
Les propriétés utilisées dans cet exemple comprennent :
  • name, le nom d’affichage du client dans Metronome.
  • ingest_aliases, une liste d’identifiants utilisée pour faire correspondre un client Metronome à un événement d’utilisation. Les alias d’ingestion sont utiles si vous voulez commencer à faire circuler l’utilisation pour les clients avant qu’ils ne soient créés dans Metronome. Pour ce faire, utilisez l’ID de la table client de votre application.
Nouveau client
Dans l’exemple, vous avez associé le client nouvellement créé à l’alias d’ingestion team@example.com, donc l’événement précédent est correctement apparié. Après avoir configuré le client pour la facturation dans la prochaine section, cet événement contribuera à leur facture actuelle.
Métrique facturable pour le client

​
5. Configurer la tarification et le packaging

Ensuite, configurez les prix et le packaging, définis à l’aide de produits et de cartes tarifaires. Dans l’exemple, vous voulez facturer votre client en fonction de son utilisation de langModel4 au taux de 0,50 $ par million de tokens. La première étape est de créer un product pour votre métrique facturable. Un produit est l’endroit où vous configurez la métrique facturable pour la présentation sur la facture finale. C’est également là où vous pouvez associer la métrique à des éléments dans des systèmes externes, comme l’ID client Stripe. Apprenez les options de configuration pour les produits dans la documentation API pour le point de terminaison créer un produit. Créez un produit associé à la métrique facturable, similaire à cet exemple : 
response = client.v1.contracts.products.create(
  name="Language Model 4 Tokens (millions)",
  type="USAGE",
  billable_metric_id=billable_metric_id,  # ID from create billable metric response
  presentation_group_key=["user_id"],
  quantity_conversion={
    "conversion_factor": 1000000,
    "operation": "divide"
  }
)
  
product_id = response.data.id
Les propriétés utilisées dans cet exemple comprennent :
  • name, le nom du produit qui apparaît sur la facture. Souvent une présentation nettoyée du nom de la métrique facturable (Language Model 4 Tokens (millions) plutôt que langModel4).
  • type, détermine comment un produit est facturé. Les types pris en charge incluent usage, fixed, composite (pour les pourcentages d’autres produits d’utilisation) et subscription.
  • billable_metric_id, associe la présentation du produit à une métrique facturable existante.
  • presentation_group_key, utilisée pour regrouper les postes sur votre facture par une valeur de propriété donnée.
  • quantity_conversion, utilisée pour multiplier ou diviser les quantités affichées sur la facture finale. Par exemple, facturer par million de tokens (mTok) tout en envoyant l’utilisation au niveau du token individuel.
Métrique facturable convertie
Ensuite, attachez un prix pour le produit en ajoutant des taux à une carte tarifaire. Construisez une carte tarifaire pour votre nouveau produit, similaire à cet exemple : 
response = client.v1.contracts.rate_cards.create(
  name="Language Model List Pricing",
  description="Prices for all language models.",
)
  
rate_card_id = response.data.id
  
response = client.v1.contracts.rate_cards.rates.add(
  rate_card_id=rate_card_id,
  product_id=product_id,
  entitled=True,
  rate_type="FLAT",
  price=50,
  starting_at="2024-01-01T00:00:00.000Z"
)
Les propriétés utilisées dans cet exemple comprennent :
  • entitled, un booléen qui indique si un taux s’affiche par défaut sur la facture d’un client. Si False, il n’apparaîtra pas sur la facture d’un client sauf s’il est remplacé au niveau du contrat.
  • rate_type, utilisé pour configurer comment un taux est appliqué à mesure que l’utilisation arrive. Les valeurs prises en charge incluent FLAT ou TIERED.
  • price, le taux lui-même. Pour USD, les valeurs sont en cents (par exemple, 100 = $1,00). Les autres devises utilisent des unités entières. Voir dénomination des devises pour les détails.
  • starting_at, utilisé pour définir le moment où le taux entre en vigueur. Pour faire évoluer vos taux au fil du temps, définissez les dates starting_at et ending_before pour assurer des mises à jour de tarification fluides.
Vous pouvez utiliser cette carte tarifaire pour tous les SKU de votre catalogue de produits.

​
6. Créer un contrat

Pour commencer à générer des factures pour un client, mettez-le sur un contrat. Un contrat est un objet qui représente les conditions qu’un client a acceptées de payer, généralement basées sur votre carte tarifaire. Au plus simple, un client peut avoir un contrat basique où il paie les prix de liste prédéfinis ; cela peut couvrir bon nombre de vos cas simples en libre-service. Si vous avez des remises ou engagements spécifiques qu’un client a négociés, configurez-les dans le contrat par-dessus les prix de liste de base. Ajoutez votre client créé à un contrat, similaire à cet exemple qui utilise la carte tarifaire Language Model List Pricing : 
response = client.v1.contracts.create(
  customer_id=metronome_customer_id,
  rate_card_id=rate_card_id,
  starting_at="2024-08-01T00:00:00.000Z"
)
Après avoir créé le contrat, les factures sont générées pour toutes les périodes de facturation qui se sont produites après la date starting_at. Les données d’utilisation de la période actuelle sont visibles dans la facture DRAFT. Les postes des factures brouillon se mettent à jour quelques secondes après que Metronome reçoit les données d’utilisation. Pour le nouveau contrat de l’exemple, l’utilisation précédemment envoyée de 1 million de tokens a été appliquée.
Nouveau contrat
Ensuite, envoyez quelques événements d’utilisation supplémentaires et voyez-les se mettre à jour en temps réel : 
response = client.v1.usage.ingest(
  usage=[
    {
      "transaction_id": "382a3069-d056-4249-824d-d288b51d7743",
      "timestamp": "2024-08-15T04:39:20Z",
      "customer_id": "team@example.com",
      "event_type": "language_model",
      "properties": {
        "model": "langModel4",
        "user_id": "johndoe",
        "tokens": 1000000
      }
    },
    {
      "transaction_id": "db64bf17-f13d-4c19-89cc-acaf878a42c6",
      "timestamp": "2024-08-16T19:11:02Z",
      "customer_id": "team@example.com",
      "event_type": "language_model",
      "properties": {
        "model": "langModel4",
        "user_id": "janedoe",
        "tokens": 5500000
      }
    },
    {
      "transaction_id": "266339fd-2125-4827-afb7-a395a7f0007f",
      "timestamp": "2024-08-17T12:51:32Z",
      "customer_id": "team@example.com",
      "event_type": "language_model",
      "properties": {
        "model": "langModel4",
        "user_id": "johndoe",
        "tokens": 3000000
      }
    },
  ]
)
Après avoir actualisé la facture, les valeurs des trois charges utiles d’événements ci-dessus s’appliquent aux totaux courants des postes. Les clés de groupe précédemment appliquées vous permettent de séparer la présentation de la facture par l’ID utilisateur associé à l’utilisation.
Contrat mis à jour