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

Alpha

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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.

Remarque : Pour en savoir plus sur la terminologie utilisée dans cette page, consultez le glossaire des API.

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.backend_latency	Latence du backend	"0.007s"

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",
      "backend_latency": "0.007s"
    },
    "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.