Créer des rapports de télémétrie

Présentation

Cette page explique comment utiliser l'API Service Control v2 pour créer des rapports de télémétrie pour les services gérés intégrés à Service Infrastructure. Elle est destinée aux producteurs de services qui souhaitent effectuer une intégration poussée de leurs services à Google Cloud.

Service Infrastructure est une plate-forme de base permettant aux développeurs de produire, gérer, sécuriser et utiliser des API et des services. Elle est basée sur un modèle d'utilisation de service simple et générique : un client utilise un service géré par un producteur. Toutes les API Google et les API Google Cloud utilisent ce modèle, car elles reposent également sur Service Infrastructure.

Lorsqu'un client accède à un service, le service transmet les données de télémétrie pertinentes à la plate-forme, de sorte que le client et le producteur peuvent observer l'accès. Avec Service Infrastructure, ce processus est appelé "rapport de télémétrie", qui inclut l'analyse, l'audit, la facturation, la journalisation et la surveillance.

API Service Control v2

L'API Service Control v2 offre une méthode services.report simple qui fournit les rapports sur la télémétrie à tous les services intégrés à Service Infrastructure. Cette méthode vous permet d'effectuer les opérations suivantes en un seul appel de méthode :

  • Analyse
  • Audits
  • Billing
  • Logging
  • Monitoring

Lorsqu'un service transmet des données de télémétrie à l'API Service Control, celles-ci sont distribuées au client, au producteur ou aux deux, en fonction de la configuration du service. Pour plus d'informations sur la configuration de la télémétrie, consultez la section sur la journalisation et la surveillance de google.api.Service.

Pour qu'un service puisse appeler l'API Service Control, le producteur doit activer l'API Service Control sur le projet producteur et l'appelant doit disposer des autorisations appropriées sur le service. Pour en savoir plus, consultez les pages Premiers pas des API Cloud et Contrôle des accès à l'API Service Control.

Attributs de requête

Lorsqu'un client accède à un service, le service doit modéliser l'accès en fonction d'un ensemble de requêtes API et décrire chaque requête à l'aide d'un objet AttributeContext.

Pour créer des rapports sur les métriques de l'API à l'aide de l'API Service Control, le service doit appeler la méthode services.report pour chaque requête comportant les attributs suivants : L'API Service Control génère les métriques de l'API et les envoie à Cloud Monitoring.

Attribut Description Exemple
origin.ip Adresse IP de l'appelant "1.2.3.4"
api.service Nom du service API "endpointsapis.appspot.com"
api.operation Nom de la méthode API "google.example.hello.v1.HelloService.GetHello"
api.version Chaîne de version de l'API "v1"
api.protocol Nom du protocole API "https"
request.id ID de requête unique "123e4567-e89b-12d3-a456-426655440000"
request.time Horodatage de la requête "2019-07-31T05:20:00Z"
request.method Nom de la méthode HTTP "POST"
request.scheme Schéma d'URL "https"
request.host En-tête de l'hôte HTTP "endpointsapis.appspot.com"
request.path Chemin de l'URL "/v1/hello"
response.code Code d'état de la réponse 200
response.size Taille de la réponse en octets 100
response.time Horodatage de la réponse "2019-07-31T05:20:02Z"
response.headers["x-backend-latency"] Latence du backend en secondes "0.007"

Effectuer des rapports sur la télémétrie

Une fois que vous avez déployé votre configuration de service sur l'API Service Management et que votre service est prêt à répondre aux requêtes des clients, vous pouvez commencer à appeler services.report pour votre service déployé. Vous devez appeler services.report pour générer des rapports de télémétrie une fois que votre service reçoit une requête.

Pour tester rapidement les rapports de télémétrie, vous pouvez utiliser la commande gcurl pour appeler la méthode services.report. Consultez la page Premiers pas avec l'API Service Control pour connaître la procédure de configuration initiale.

L'exemple suivant montre comment utiliser la commande gcurl pour appeler services.report via HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "operations": [{
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
      "version": "v1",
      "protocol": "https"
    },
    "request": {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "size": 50,
      "time": "2019-07-31T05:20:00Z",
    },
    "response": {
      "size": 100,
      "code": 200,
      "time": "2019-07-31T05:20:02Z",
      "headers": {
        "x-backend-latency": "0.007"
      }
    },
    "destination": {
      "region_code": "us-central1"
    }
    "resource": {
      "name": "projects/123/locations/us-central1/workspaces/default"
    }
  }]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report

Si la requête aboutit, la réponse de la méthode services.report doit être vide. En cas d'échec, l'erreur d'API doit contenir des informations détaillées sur l'erreur. Pour en savoir plus sur la gestion des erreurs, consultez le Guide de conception d'API > Erreurs.

Pour les services de production, vous devez utiliser l'une des bibliothèques clientes fournies par Google pour appeler l'API Service Control. Ces bibliothèques offrent une grande facilité d'utilisation et gèrent automatiquement les fonctionnalités courantes, telles que l'authentification. Pour en savoir plus, consultez la section Présentation des bibliothèques clientes.