feat(samples): add samples (#229)

packages/google-cloud-datacatalog/.jsdoc.js

@@ -1,4 +1,4 @@
-// Copyright 2020 Google LLC
+// Copyright 2021 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -40,7 +40,7 @@ module.exports = {
     includePattern: '\\.js$'
   },
   templates: {
-    copyright: 'Copyright 2020 Google LLC',
+    copyright: 'Copyright 2021 Google LLC',
     includeDate: false,
     sourceFiles: false,
     systemName: '@google-cloud/datacatalog',

packages/google-cloud-datacatalog/CONTRIBUTING.md

@@ -37,6 +37,15 @@ accept your pull requests.
 1.  Title your pull request following [Conventional Commits](https://www.conventionalcommits.org/) styling.
 1.  Submit a pull request.
 
+### Before you begin
+
+1.  [Select or create a Cloud Platform project][projects].
+1.  [Enable billing for your project][billing]. 
+1.  [Enable the Data Catalog API][enable_api]. 
+1.  [Set up authentication with a service account][auth] so you can access the
+    API from your local workstation.
+
+
 ## Running the tests
 
 1.  [Prepare your environment for Node.js setup][setup].
@@ -51,15 +60,17 @@ accept your pull requests.
         npm test
 
         # Run sample integration tests.
-        gcloud auth application-default login
         npm run samples-test
 
         # Run all system tests.
-        gcloud auth application-default login
         npm run system-test
 
 1.  Lint (and maybe fix) any changes:
 
         npm run fix
 
 [setup]: https://cloud.google.com/nodejs/docs/setup
+[projects]: https://console.cloud.google.com/project
+[billing]: https://support.google.com/cloud/answer/6293499#enable-billing
+[enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=datacatalog.googleapis.com
+[auth]: https://cloud.google.com/docs/authentication/getting-started

packages/google-cloud-datacatalog/README.md

@@ -32,8 +32,8 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
 * [Quickstart](#quickstart)
   * [Before you begin](#before-you-begin)
   * [Installing the client library](#installing-the-client-library)
-
-
+  * [Using the client library](#using-the-client-library)
+* [Samples](#samples)
 * [Versioning](#versioning)
 * [Contributing](#contributing)
 * [License](#license)
@@ -55,6 +55,174 @@ npm install @google-cloud/datacatalog
 ```
 
 
+### Using the client library
+
+```javascript
+// Import the Google Cloud client library and create a client.
+const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
+const datacatalog = new DataCatalogClient();
+
+async function quickstart() {
+  // Common fields.
+  let request;
+  let responses;
+
+  /**
+   * TODO(developer): Uncomment the following lines before running the sample.
+   */
+  // const projectId = 'my_project'; // Google Cloud Platform project
+  // const datasetId = 'demo_dataset';
+  // const tableId = 'trips';
+
+  // Currently, Data Catalog stores metadata in the
+  // us-central1 region.
+  const location = 'us-central1';
+
+  // Create Fields.
+  const fieldSource = {
+    displayName: 'Source of data asset',
+    type: {
+      primitiveType: 'STRING',
+    },
+  };
+
+  const fieldNumRows = {
+    displayName: 'Number of rows in data asset',
+    type: {
+      primitiveType: 'DOUBLE',
+    },
+  };
+
+  const fieldHasPII = {
+    displayName: 'Has PII',
+    type: {
+      primitiveType: 'BOOL',
+    },
+  };
+
+  const fieldPIIType = {
+    displayName: 'PII type',
+    type: {
+      enumType: {
+        allowedValues: [
+          {
+            displayName: 'EMAIL',
+          },
+          {
+            displayName: 'SOCIAL SECURITY NUMBER',
+          },
+          {
+            displayName: 'NONE',
+          },
+        ],
+      },
+    },
+  };
+
+  // Create Tag Template.
+  const tagTemplateId = 'demo_tag_template';
+
+  const tagTemplate = {
+    displayName: 'Demo Tag Template',
+    fields: {
+      source: fieldSource,
+      num_rows: fieldNumRows,
+      has_pii: fieldHasPII,
+      pii_type: fieldPIIType,
+    },
+  };
+
+  const tagTemplatePath = datacatalog.tagTemplatePath(
+    projectId,
+    location,
+    tagTemplateId
+  );
+
+  // Delete any pre-existing Template with the same name.
+  try {
+    request = {
+      name: tagTemplatePath,
+      force: true,
+    };
+    await datacatalog.deleteTagTemplate(request);
+    console.log(`Deleted template: ${tagTemplatePath}`);
+  } catch (error) {
+    console.log(`Cannot delete template: ${tagTemplatePath}`);
+  }
+
+  // Create the Tag Template request.
+  const locationPath = datacatalog.locationPath(projectId, location);
+
+  request = {
+    parent: locationPath,
+    tagTemplateId: tagTemplateId,
+    tagTemplate: tagTemplate,
+  };
+
+  // Execute the request.
+  responses = await datacatalog.createTagTemplate(request);
+  const createdTagTemplate = responses[0];
+  console.log(`Created template: ${createdTagTemplate.name}`);
+
+  // Lookup Data Catalog's Entry referring to the table.
+  responses = await datacatalog.lookupEntry({
+    linkedResource:
+      '//bigquery.googleapis.com/projects/' +
+      `${projectId}/datasets/${datasetId}/tables/${tableId}`,
+  });
+  const entry = responses[0];
+  console.log(`Entry name: ${entry.name}`);
+  console.log(`Entry type: ${entry.type}`);
+  console.log(`Linked resource: ${entry.linkedResource}`);
+
+  // Attach a Tag to the table.
+  const tag = {
+    name: entry.name,
+    template: createdTagTemplate.name,
+    fields: {
+      source: {
+        stringValue: 'copied from tlc_yellow_trips_2017',
+      },
+      num_rows: {
+        doubleValue: 113496874,
+      },
+      has_pii: {
+        boolValue: false,
+      },
+      pii_type: {
+        enumValue: {
+          displayName: 'NONE',
+        },
+      },
+    },
+  };
+
+  request = {
+    parent: entry.name,
+    tag: tag,
+  };
+
+  // Create the Tag.
+  await datacatalog.createTag(request);
+  console.log(`Tag created for entry: ${entry.name}`);
+}
+quickstart();
+
+```
+
+
+
+## Samples
+
+Samples are in the [`samples/`](https://github.com/googleapis/nodejs-datacatalog/tree/master/samples) directory. Each sample's `README.md` has instructions for running its sample.
+
+| Sample                      | Source Code                       | Try it |
+| --------------------------- | --------------------------------- | ------ |
+| Create Custom Entry | [source code](https://github.com/googleapis/nodejs-datacatalog/blob/master/samples/createCustomEntry.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-datacatalog&page=editor&open_in_editor=samples/createCustomEntry.js,samples/README.md) |
+| Create Fileset | [source code](https://github.com/googleapis/nodejs-datacatalog/blob/master/samples/createFileset.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-datacatalog&page=editor&open_in_editor=samples/createFileset.js,samples/README.md) |
+| Grant Tag Template User Role | [source code](https://github.com/googleapis/nodejs-datacatalog/blob/master/samples/grantTagTemplateUserRole.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-datacatalog&page=editor&open_in_editor=samples/grantTagTemplateUserRole.js,samples/README.md) |
+| Quickstart | [source code](https://github.com/googleapis/nodejs-datacatalog/blob/master/samples/quickstart.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-datacatalog&page=editor&open_in_editor=samples/quickstart.js,samples/README.md) |
+| Search Assets | [source code](https://github.com/googleapis/nodejs-datacatalog/blob/master/samples/searchAssets.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/nodejs-datacatalog&page=editor&open_in_editor=samples/searchAssets.js,samples/README.md) |
 
 
 
@@ -67,7 +235,7 @@ Our client libraries follow the [Node.js release schedule](https://nodejs.org/en
 Libraries are compatible with all current _active_ and _maintenance_ versions of
 Node.js.
 
-Client libraries targetting some end-of-life versions of Node.js are available, and
+Client libraries targeting some end-of-life versions of Node.js are available, and
 can be installed via npm [dist-tags](https://docs.npmjs.com/cli/dist-tag).
 The dist-tags follow the naming convention `legacy-(version)`.