Tutoriel NerdGraph : diffusez vos données vers AWS Kinesis Firehose, Azure Event Hub ou GCP Pub/Sub

Cette API vous permet de créer une règle d’exportation en streaming pour envoyer des données à AWS Kinesis Firehose.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportCreateRule(
    accountId: YOUR_NR_ACCOUNT_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "SELECT * FROM NodeStatus"
      payloadCompression: DISABLED
    }
    awsParameters: {
      awsAccountId: "YOUR_AWS_ACCOUNT_ID"
      deliveryStreamName: "FIREHOSE_STREAM_NAME"
      region: "SPECIFY_AWS_REGION"
      role: "firehose-role"
    }
  ) {
    id
    status
  }
}

Réponse: vous recevez une réponse avec l’ID de la règle, et le statut. Le statut sera CREATION_IN_PROGRESS initialement, et la création de la règle peut prendre jusqu’à six minutes.
Points à noter: avant que la règle ne termine son enregistrement, vous ne pouvez pas initier d’autre action de mutation (comme Enable, Disable, ou Update) car la règle est verrouillée pour le processus de création. Si vous essayez une autre action de mutation avant que la règle ne termine le processus d’enregistrement, vous obtiendrez un message du type : « La règle d’exportation est actuellement en cours de mise à jour par une autre requête, veuillez patienter et réessayer plus tard. »

Vous pouvez utiliser Delete à tout moment.

La création peut être terminée et le statut peut être modifié à tout moment dans les six minutes environ nécessaires à la création de la règle. Le statut passera à ENABLED, DISABLED ou CREATION_FAILED.

Voir ces détails sur les valeurs :

• ENABLED signifie que la règle a été créée avec succès et que les données ont commencé à être diffusées.
• CREATION_FAILED signifie que la règle a échoué lors de la création. Cela peut se produire pour plusieurs raisons, mais est souvent dû à l’échec de la politique AWS ou de la validation Azure SAS.
• DISABLED signifie que la règle est créée mais n'est pas encore activée pour des raisons telles que la limite du flux de filtrage atteinte ou l'échec de la création de la règle de flux de filtrage. Si le statut reste CREATION_IN_PROGRESS après six minutes, cela signifie que la création de la règle a échoué en raison d'une erreur système sur notre service. Vous pouvez supprimer la règle et essayer d'en créer une nouvelle.

Cette API vous permet de récupérer une liste complète de toutes les règles de flux associées à votre ID de compte.

Demande d'échantillon

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRules {
          aws {
            awsAccountId
            region
            deliveryStreamName
            role
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Cette API vous permet d’interroger des informations sur une règle de flux spécifique en fournissant l’ID de compte et l’ID de règle.

Demande d'échantillon

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRule(id: "RULE_ID") {
          aws {
            awsAccountId
            deliveryStreamName
            region
            role
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Cette API vous permet de modifier une règle d'exportation de streaming existante.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportUpdateRule(
    id: RULE_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "YOUR_NRQL_QUERY"
      payloadCompression: DISABLED
    }
    awsParameters: {
      awsAccountId: "YOUR_AWS_ACCOUNT_ID"
      deliveryStreamName: "FIREHOSE_STREAM_NAME"
      region: "SPECIFY_AWS_REGION"
      role: "firehose-role"
    }
  ) {
    id
    status
  }
}

Réponse: vous recevez une réponse avec l’ID de la règle, et le statut.
Points à noter: lors de la mise à jour, vous recevrez un message dans le champ de message : « La règle d’exportation est en cours de mise à jour, et le processus peut prendre quelques minutes pour se terminer. Veuillez vérifier à nouveau plus tard. » La mise à jour complète peut prendre jusqu’à six minutes.

Vous pouvez vérifier si la règle est mise à jour en appelant streamingRule pour récupérer la règle. Pendant la période de mise à jour de la règle, la règle est verrouillée, et aucune autre action de mutation ne peut agir sur la règle. Si vous essayez d’effectuer une autre action de mutation sur la même règle, vous recevrez un message indiquant : « La règle d’exportation est actuellement mise à jour par une autre requête, veuillez patienter, et réessayer plus tard. » Un utilisateur peut mettre à jour une règle de n’importe quel statut, à l’exception d’une règle supprimée.

Cette API vous permet d’activer une règle de flux existante, facilitant l’exportation continue de données pour un traitement en temps réel et une intégration avec d’autres services.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportEnableRule(id: RULE_ID) {
    id
    status
    message
  }
}

Réponse: si vous essayez d’activer une règle qui se trouve dans un autre état, cela renvoie le message d’erreur suivant : « La règle d’exportation ne peut pas être activée, ou désactivée en raison d’un statut non autorisé. » Vous ne pouvez pas activer la règle si la règle est verrouillée en raison d’une autre mutation en cours.

Cette API vous permet de désactiver une règle de streaming existante, arrêtant l’exportation continue de données.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportDisableRule(id: RULE_ID) {
    id
    status
    message
  }
}

Réponse: si vous essayez de désactiver une règle qui se trouve dans un autre état, cela renvoie un message d’erreur tel que : « The export rule can’t be enabled or disabled due to status not being allowed. » Vous ne pouvez pas désactiver la règle si elle est verrouillée en raison d’une autre mutation en cours.

Cette API vous permet de supprimer une règle de streaming, et d’arrêter toute exportation de données liée à cette règle.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportDeleteRule(id: RULE_ID) {
    id
  }
}

Cette API vous permet de créer une règle d'exportation de streaming pour envoyer des données à un Azure Event Hub.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportCreateRule(
    accountId: YOUR_NR_ACCOUNT_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "SELECT * FROM NodeStatus"
      payloadCompression: DISABLED
    }
    azureParameters: {
      eventHubConnectionString: "YOUR_EVENT_HUB_SAS_CONNECTION_STRING"
      eventHubName: "YOUR_EVENT_HUB_NAME"
    }
  ) {
    id
    status
  }
}

Réponse: vous recevez une réponse avec l’ID de la règle, et le statut. Le statut sera CREATION_IN_PROGRESS initialement, et la création de la règle peut prendre jusqu’à six minutes.

Cette API vous permet de récupérer une liste complète de toutes les règles de flux associées à votre ID de compte.

Demande d'échantillon

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRules {
          azure {
            eventHubConnectionString
            eventHubName
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Cette API vous permet d’interroger des informations sur une règle de flux spécifique en fournissant l’ID de compte et l’ID de règle.

Demande d'échantillon

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRule(id: "RULE_ID") {
          azure {
            eventHubConnectionString
            eventHubName
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Cette API vous permet de modifier une règle d'exportation de streaming existante.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportUpdateRule(
    id: RULE_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "YOUR_NRQL_QUERY"
      payloadCompression: DISABLED
    }
    azureParameters: {
      eventHubConnectionString: "YOUR_EVENT_HUB_SAS_CONNECTION_STRING"
      eventHubName: "YOUR_EVENT_HUB_NAME"
    }
  ) {
    id
    status
  }
}

Réponse: vous recevez une réponse avec l’ID de la règle et le statut.

Pour activer une règle de streaming existante, facilitant l’exportation continue de données pour un traitement en temps réel et une intégration avec d’autres services, consultez cette section.

Pour désactiver une règle de streaming existante, arrêtant l’exportation continue de données, reportez-vous ici.

Pour supprimer une règle de flux et arrêter toute exportation de données liée à cette règle, reportez-vous ici.

Cette API vous permet de créer une règle d’exportation en streaming pour envoyer des données à GCP Pub/Sub.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportCreateRule(
    accountId: YOUR_NR_ACCOUNT_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "SELECT * FROM NodeStatus"
      payloadCompression: DISABLED
    }
    gcpParameters: {
      gcpProjectId: "project-id"
      pubsubTopicId: "pub-sub-topic-id"
    }
  ) {
    id
    status
  }
}

Réponse: vous recevez une réponse avec l’ID de la règle, et le statut. Le statut sera CREATION_IN_PROGRESS initialement, et la création de la règle peut prendre jusqu’à six minutes.

Cette API vous permet de récupérer une liste complète de toutes les règles de flux associées à votre ID de compte.

Demande d'échantillon

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRules {
          gcp {
            gcpProjectId
            pubsubTopicId
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Cette API vous permet d’interroger des informations sur une règle de flux spécifique en fournissant l’ID de compte et l’ID de règle.

Demande d'échantillon

{
  actor {
    account(id: YOUR_NR_ACCOUNT_ID) {
      streamingExport {
        streamingRule(id: "RULE_ID") {
          gcp {
            gcpProjectId
            pubsubTopicId
          }
          createdAt
          description
          id
          message
          name
          nrql
          status
          updatedAt
          payloadCompression
        }
      }
    }
  }
}

Cette API vous permet de modifier une règle d'exportation de streaming existante.

Paramètres d'entrée

Demande d'échantillon

mutation {
  streamingExportUpdateRule(
    id: RULE_ID
    ruleParameters: {
      description: "ADD_RULE_DESCRIPTION"
      name: "PROVIDE_RULE_NAME"
      nrql: "YOUR_NRQL_QUERY"
      payloadCompression: DISABLED
    }
    gcpParameters: {
      gcpProjectId: "project-id"
      pubsubTopicId: "pub-sub-topic-id"
    }
  ) {
    id
    status
  }
}

Réponse: vous recevez une réponse avec l’ID de la règle et le statut.

Pour activer une règle de streaming existante, facilitant l’exportation continue de données pour un traitement en temps réel et une intégration avec d’autres services, consultez cette section.

Pour désactiver une règle de streaming existante, arrêtant l’exportation continue de données, reportez-vous ici.

Pour supprimer une règle de flux et arrêter toute exportation de données liée à cette règle, reportez-vous ici.

Les points d'accès fonctionnent comme des méthodes distinctes par lesquelles les objets des compartiments S3 peuvent être consultés et téléchargés. AWS fournit une fonctionnalité appelée points d'accès Object Lambda, qui exécutent une fonction Lambda sur chaque objet S3 accessible via le point d'accès. Suivez ces étapes pour activer un tel point d’accès :

1. Accédez à cette page, cliquez sur le lien vers le référentiel serverless (repository).

2. Cliquez sur Deploy.

3. Configurez un point d’accès sur votre bucket S3.

4. Créer un point d’accès Object Lambda. Ce point d'accès doit avoir ces paramètres :

   • Le Supporting Access Point sur ce point d’accès Lambda devra être défini sur le point d’accès que vous avez configuré sur le bucket S3.
   • Sous Transformation Configuration:
   • Sélectionnez GetObject.
   • Spécifiez la fonction Lambda DecompressGZFunction, ou une autre fonction nécessaire si vous utilisez un format de compression différent.

AWS décompressera automatiquement les objets téléchargés depuis S3, si ces objets disposent du bon ensemble de métadonnées. Nous avons écrit une fonction qui applique automatiquement ces métadonnées à chaque nouvel objet téléchargé dans un ensemble d'objets S3. Voici comment le configurer :

1. Naviguez ici, clonez le référentiel localement et suivez les étapes fournies dans le fichier README pour générer un fichier ZIP contenant la fonction Lambda.
2. Créez un rôle IAM pour la fonction.

• Lors de la création du rôle, assurez-vous de définir le type d'entité de confiance sur « services AWS», avec « Lambda» comme cas d'utilisation.
• Ce rôle doit avoir une politique avec ces autorisations : s3:PutObject et s3:GetObject.

3. Dans AWS, accédez à la page de fonction Lambda .

4. Cliquez sur Create function.

5. Sélectionnez l’environnement d’exécution Java 11.

6. Cliquez sur Change default execution role > Use an existing role. Saisissez ici le rôle que vous avez créé à l’étape 2.

7. Faites défiler vers le bas et cliquez sur Create function.

8. Une fois la fonction créée, cliquez sur Upload from et sélectionnez .zip or .jar file dans la liste déroulante.

9. Cliquez sur Upload dans la boîte qui s’affiche et sélectionnez le fichier ZIP créé à l’étape 1.

10. Une fois le téléchargement terminé, cliquez sur Save pour quitter la boîte contextuelle.

11. Modifiez Runtime settings en ajoutant le gestionnaire. Dans notre fonction fournie, le gestionnaire est metadatasetter.App::handleRequest.

12. Il ne reste plus qu'à activer cette fonction Lambda pour qu'elle se déclenche lors de la création d'un objet S3. Cliquez sur Add trigger pour commencer la configuration.

13. Dans la liste déroulante, sélectionnez S3 comme source.

14. Saisissez le nom du bucket S3 auquel vous souhaitez appliquer les métadonnées dans le champ Bucket .

15. Supprimez la valeur par défaut All object create events des types d’événements. Dans la liste déroulante des types d'événements, sélectionnez PUT.

16. Cochez la case Recursive invocation , puis cliquez sur Add en bas à droite.

    La fonction Lambda va maintenant commencer à ajouter automatiquement les métadonnées de compression à tous les objets S3 nouvellement ajoutés.