Tutorial de NerdGraph: Administrar clave de API

Este documento contiene tutoriales sobre cómo usar NerdGraph para administrar mediante programación algunas claves de API de New Relic: la clave de licencia, la clave del browser y el clave de usuario. Para obtener información general sobre nuestras claves, consulte clave de API.

Descripción general de la descripción de características

Puede utilizar la clave de API UI para crear y administrar claves. Alternativamente, puede usar el campo ApiAccess de NerdGraph para crear y administrar mediante programación los siguientes tipos de claves:

• Claves de usuario, necesarias para utilizar NerdGraph

• Claves de ingesta de datos, que incluyen:

  • El clave de licencia: necesario para la ingesta de la mayoría de los datos en New Relic, excepto los datos monitoreo de browserymonitoreo de aplicaciones móviles
  • Clave del navegador: requerida para la ingesta de datos de monitoreo del navegador

Un caso de uso común de esta característica es la capacidad de rotar claves por motivos de seguridad. Tenga en cuenta que no puede utilizar esta funcionalidad de NerdGraph para eliminar la clave de licencia o la clave browser que se creó originalmente con una cuenta; esas claves originales no se pueden eliminar. Solo puedes crear claves de licencia adicionales y administrar las que hayas creado.

Notas sobre esta funcionalidad:

• Todas las mutaciones pueden aceptar múltiples claves como argumentos y devolverán detalles sobre cambios y errores exitosos. Consulte los ejemplos a continuación para obtener más detalles.

• Todas las mutaciones (crear, actualizar y eliminar) darán como resultado un NrAuditEvent que se puede consultar con fines de auditoría. Para obtener más información, consulte Evento de auditoría.

• Con respecto a las claves de ingesta:

  • Las claves de licencia y de Browser son categorizadas por NerdGraph como ingest keys. Esto se debe a que su uso principal es permitir la ingesta de datos.
  • Puede crear hasta 1000 claves de cada tipo de clave de ingesta, lo que permite la rotación de claves.
  • No puede administrar ni eliminar las claves de ingesta originales de la cuenta, pero puede comunicarse con el soporte de New Relic para rotarlas; solo puede crear claves de ingesta o de usuario adicionales y administrar las claves que ha creado.

Antes de usar ejemplos

Cosas a tener en cuenta antes de utilizar estas consultas de ejemplo:

• Para comprender la estructura de datos, recomendamos experimentar con consulta utilizando el explorador GraphiQL.
• También puede crear, ver y eliminar claves de usuario mediante la UI.

Crear claves

Para crear varias claves (clave de usuario o clave de ingesta) en una sola mutación, para varias cuentas y tipos de claves. Tenga en cuenta que la mutación puede devolver las claves creadas correctamente, así como cualquier error encontrado al intentar crear claves.

Ejemplo de creación de una clave:

mutation {
  apiAccessCreateKeys(
    keys: {
      ingest: {
        accountId: YOUR_ACCOUNT_ID
        ingestType: BROWSER
        name: "Browser Key"
        notes: "A note."
        owningTeamIds: [TEAM_ID]
      }
    }
  ) {
    createdKeys {
      id
      key
      obfuscatedKey
      name
      notes
      type
      enabled
      createdAt
      ... on ApiAccessIngestKey {
        ingestType
      }
    }
    errors {
      message
      type
      ... on ApiAccessIngestKeyError {
        accountId
        errorType
        ingestType
      }
    }
  }
}

Los resultados variarán dependiendo de sus datos. Utilice el explorador GraphiQL para experimentar con mutaciones y realizar consultas.

A continuación se muestra un ejemplo del uso de esta consulta para crear una clave de usuario:

Crear una clave de usuario

Para crear una clave de usuario, cambiaría ligeramente la consulta anterior, en la sección keys :

mutation {
  apiAccessCreateKeys(
    keys: { user: { accountId: YOUR_ACCOUNT_ID, userId: YOUR_USER_ID } }
  ) {
    createdKeys {
      id
      key
      name
      notes
      type
      ... on ApiAccessIngestKey {
        ingestType
      }
    }
    errors {
      message
      type
      ... on ApiAccessIngestKeyError {
        accountId
        errorType
        ingestType
      }
    }
  }
}

Actualizar claves

La mutación de actualización toma el ID de la clave, no la cadena de claves, para identificar las claves.

mutation {
  apiAccessUpdateKeys(
    keys: {
      ingest: {
        keyId: KEY_ID
        name: "Updated name"
        notes: "A new note!"
        enabled: true
        owningTeamIds: [TEAM_ID]
      }
    }
  ) {
    updatedKeys {
      id
      key
      obfuscatedKey
      type
      name
      notes
      enabled
      createdAt
    }
    errors {
      message
    }
  }
}

Utilice enabled para activar o desactivar una clave sin eliminarla: enabled: true desactiva la clave y enabled: false la mantiene activa. Utilice owningTeamIds para asignar uno o más equipos a la clave.

Los resultados variarán dependiendo de sus datos. Utilice el explorador GraphiQL para experimentar con mutaciones y realizar consultas.

Eliminar claves

La mutación de eliminación toma el ID de la clave, no la cadena de claves, para identificar las claves. Las claves eliminadas ya no otorgarán acceso a los sistemas New Relic y ya no se devolverán mediante consulta a la API GraphQL de acceso a la API.

mutation {
  apiAccessDeleteKeys(keys: { ingestKeyIds: INGEST_KEY_ID }) {
    deletedKeys {
      id
    }
    errors {
      message
    }
  }
}

Los resultados variarán dependiendo de sus datos. Utilice el explorador GraphiQL para experimentar con mutaciones y realizar consultas.

Claves de consulta

Puede acceder a las claves de ingesta y de usuario consultando una sola clave o todas las claves, en el ámbito de actor. Si consulta una sola clave, debe proporcionar el ID y el tipo de clave (INGEST o USER). La consulta de varias claves se realiza mediante una búsqueda de claves, que utiliza una lista de tipos obligatoria y un alcance opcional para filtrar los resultados. Las claves de usuario que pertenecen a otros usuarios se ofuscarán en los resultados.

Consulta de ejemplo clave única:

query {
  actor {
    apiAccess {
      key(id: "INGEST_KEY_ID", keyType: INGEST) {
        key
        name
        type
        ... on ApiAccessIngestKey {
          ingestType
        }
      }
    }
  }
}

Consulta de ejemplo de búsqueda clave:

query {
  actor {
    apiAccess {
      keySearch(query: { types: INGEST, scope: { ingestTypes: BROWSER } }) {
        keys {
          name
          key
          type
          ... on ApiAccessIngestKey {
            ingestType
          }
        }
      }
    }
  }
}

Para recuperar el último timestamp utilizado para una clave de usuario, utilice el campo keyUsage con el ID de la clave:

query {
  actor {
    apiAccess {
      keyUsage(keyIds: "USER_KEY_ID") {
        keyId
        lastUsedAt
      }
    }
  }
}

lastUsedAt solo está disponible para claves de usuario. No es compatible con las claves de ingesta de licencia ni con las claves de ingesta de navegador. keyUsage devuelve una matriz, por lo que puede pasar varios ID de clave y utilizar keyId en la respuesta para identificar qué resultado pertenece a qué clave.

Los resultados variarán dependiendo de sus datos. Utilice el explorador GraphiQL para experimentar con mutaciones y realizar consultas.