Skip to content

Commit 4eb6d9e

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
docs: Improvements to DataScan API documentation
PiperOrigin-RevId: 506348044
1 parent 8617368 commit 4eb6d9e

1 file changed

Lines changed: 65 additions & 52 deletions

File tree

‎google/cloud/dataplex/v1/datascans.proto‎

Lines changed: 65 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -33,12 +33,15 @@ option java_multiple_files = true;
3333
option java_outer_classname = "DataScansProto";
3434
option java_package = "com.google.cloud.dataplex.v1";
3535

36+
// DataScanService manages DataScan resources which can be configured to run
37+
// various types of data scanning workload and generate enriched metadata (e.g.
38+
// Data Profile, Data Quality) for the data source.
3639
service DataScanService {
3740
option (google.api.default_host) = "dataplex.googleapis.com";
3841
option (google.api.oauth_scopes) =
3942
"https://www.googleapis.com/auth/cloud-platform";
4043

41-
// Creates a dataScan resource.
44+
// Creates a DataScan resource.
4245
rpc CreateDataScan(CreateDataScanRequest)
4346
returns (google.longrunning.Operation) {
4447
option (google.api.http) = {
@@ -52,7 +55,7 @@ service DataScanService {
5255
};
5356
}
5457

55-
// Update the dataScan resource.
58+
// Updates a DataScan resource.
5659
rpc UpdateDataScan(UpdateDataScanRequest)
5760
returns (google.longrunning.Operation) {
5861
option (google.api.http) = {
@@ -66,7 +69,7 @@ service DataScanService {
6669
};
6770
}
6871

69-
// Delete the dataScan resource.
72+
// Deletes a DataScan resource.
7073
rpc DeleteDataScan(DeleteDataScanRequest)
7174
returns (google.longrunning.Operation) {
7275
option (google.api.http) = {
@@ -79,23 +82,23 @@ service DataScanService {
7982
};
8083
}
8184

82-
// Get dataScan resource.
85+
// Gets a DataScan resource.
8386
rpc GetDataScan(GetDataScanRequest) returns (DataScan) {
8487
option (google.api.http) = {
8588
get: "/v1/{name=projects/*/locations/*/dataScans/*}"
8689
};
8790
option (google.api.method_signature) = "name";
8891
}
8992

90-
// Lists dataScans.
93+
// Lists DataScans.
9194
rpc ListDataScans(ListDataScansRequest) returns (ListDataScansResponse) {
9295
option (google.api.http) = {
9396
get: "/v1/{parent=projects/*/locations/*}/dataScans"
9497
};
9598
option (google.api.method_signature) = "parent";
9699
}
97100

98-
// Run an on demand execution of a DataScan.
101+
// Runs an on-demand execution of a DataScan
99102
rpc RunDataScan(RunDataScanRequest) returns (RunDataScanResponse) {
100103
option (google.api.http) = {
101104
post: "/v1/{name=projects/*/locations/*/dataScans/*}:run"
@@ -104,15 +107,15 @@ service DataScanService {
104107
option (google.api.method_signature) = "name";
105108
}
106109

107-
// Get DataScanJob resource.
110+
// Gets a DataScanJob resource.
108111
rpc GetDataScanJob(GetDataScanJobRequest) returns (DataScanJob) {
109112
option (google.api.http) = {
110113
get: "/v1/{name=projects/*/locations/*/dataScans/*/jobs/*}"
111114
};
112115
option (google.api.method_signature) = "name";
113116
}
114117

115-
// Lists DataScanJobs under the given dataScan.
118+
// Lists DataScanJobs under the given DataScan.
116119
rpc ListDataScanJobs(ListDataScanJobsRequest)
117120
returns (ListDataScanJobsResponse) {
118121
option (google.api.http) = {
@@ -125,8 +128,8 @@ service DataScanService {
125128
// Create dataScan request.
126129
message CreateDataScanRequest {
127130
// Required. The resource name of the parent location:
128-
// projects/{project}/locations/{location_id}
129-
// where `{project}` refers to a project_id or project_number and
131+
// `projects/{project}/locations/{location_id}`
132+
// where `project` refers to a *project_id* or *project_number* and
130133
// `location_id` refers to a GCP region.
131134
string parent = 1 [
132135
(google.api.field_behavior) = REQUIRED,
@@ -139,6 +142,7 @@ message CreateDataScanRequest {
139142
DataScan data_scan = 2 [(google.api.field_behavior) = REQUIRED];
140143

141144
// Required. DataScan identifier.
145+
//
142146
// * Must contain only lowercase letters, numbers and hyphens.
143147
// * Must start with a letter.
144148
// * Must end with a number or a letter.
@@ -149,7 +153,8 @@ message CreateDataScanRequest {
149153

150154
// Update dataScan request.
151155
message UpdateDataScanRequest {
152-
// Required. Update description.
156+
// Required. DataScan resource to be updated.
157+
//
153158
// Only fields specified in `update_mask` are updated.
154159
DataScan data_scan = 1 [(google.api.field_behavior) = REQUIRED];
155160

@@ -161,8 +166,8 @@ message UpdateDataScanRequest {
161166
// Delete dataScan request.
162167
message DeleteDataScanRequest {
163168
// Required. The resource name of the dataScan:
164-
// projects/{project}/locations/{location_id}/dataScans/{data_scan_id}
165-
// where `{project}` refers to a project_id or project_number and
169+
// `projects/{project}/locations/{location_id}/dataScans/{data_scan_id}`
170+
// where `project` refers to a *project_id* or *project_number* and
166171
// `location_id` refers to a GCP region.
167172
string name = 1 [
168173
(google.api.field_behavior) = REQUIRED,
@@ -174,21 +179,21 @@ message DeleteDataScanRequest {
174179

175180
// Get dataScan request.
176181
message GetDataScanRequest {
177-
// DataScan views for getting a partial dataScan.
182+
// DataScan view options.
178183
enum DataScanView {
179184
// The API will default to the `BASIC` view.
180185
DATA_SCAN_VIEW_UNSPECIFIED = 0;
181186

182-
// Basic view that does not include spec and result.
187+
// Basic view that does not include *spec* and *result*.
183188
BASIC = 1;
184189

185190
// Include everything.
186191
FULL = 10;
187192
}
188193

189194
// Required. The resource name of the dataScan:
190-
// projects/{project}/locations/{location_id}/dataScans/{data_scan_id}
191-
// where `{project}` refers to a project_id or project_number and
195+
// `projects/{project}/locations/{location_id}/dataScans/{data_scan_id}`
196+
// where `project` refers to a *project_id* or *project_number* and
192197
// `location_id` refers to a GCP region.
193198
string name = 1 [
194199
(google.api.field_behavior) = REQUIRED,
@@ -197,15 +202,15 @@ message GetDataScanRequest {
197202
}
198203
];
199204

200-
// Optional. Used to select the subset of DataScan information to return.
201-
// Defaults to `BASIC`.
205+
// Optional. Select the DataScan view to return. Defaults to `BASIC`.
202206
DataScanView view = 2 [(google.api.field_behavior) = OPTIONAL];
203207
}
204208

205209
// List dataScans request.
206210
message ListDataScansRequest {
207-
// Required. projects/{project}/locations/{location_id}
208-
// where `{project}` refers to a project_id or project_number and
211+
// Required. The resource name of the parent location:
212+
// `projects/{project}/locations/{location_id}`
213+
// where `project` refers to a *project_id* or *project_number* and
209214
// `location_id` refers to a GCP region.
210215
string parent = 1 [
211216
(google.api.field_behavior) = REQUIRED,
@@ -228,14 +233,14 @@ message ListDataScansRequest {
228233
// Optional. Filter request.
229234
string filter = 4 [(google.api.field_behavior) = OPTIONAL];
230235

231-
// Optional. Order by fields (name or create_time) for the result.
236+
// Optional. Order by fields (`name` or `create_time`) for the result.
232237
// If not specified, the ordering is undefined.
233238
string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
234239
}
235240

236241
// List dataScans response.
237242
message ListDataScansResponse {
238-
// DataScans (metadata only) under the given parent location.
243+
// DataScans (`BASIC` view only) under the given parent location.
239244
repeated DataScan data_scans = 1;
240245

241246
// Token to retrieve the next page of results, or empty if there are no more
@@ -249,10 +254,11 @@ message ListDataScansResponse {
249254
// Run DataScan Request
250255
message RunDataScanRequest {
251256
// Required. The resource name of the DataScan:
252-
// projects/{project}/locations/{location_id}/dataScans/{data_scan_id}.
253-
// where `{project}` refers to a project_id or project_number and
257+
// `projects/{project}/locations/{location_id}/dataScans/{data_scan_id}`.
258+
// where `project` refers to a *project_id* or *project_number* and
254259
// `location_id` refers to a GCP region.
255-
// Only on-demand DataScans are allowed.
260+
//
261+
// Only **OnDemand** data scans are allowed.
256262
string name = 1 [
257263
(google.api.field_behavior) = REQUIRED,
258264
(google.api.resource_reference) = {
@@ -263,27 +269,27 @@ message RunDataScanRequest {
263269

264270
// Run DataScan Response.
265271
message RunDataScanResponse {
266-
// DataScanJob created by RunDataScan API.
272+
// DataScanJob created by RunDataScan request.
267273
DataScanJob job = 1;
268274
}
269275

270276
// Get DataScanJob request.
271277
message GetDataScanJobRequest {
272-
// DataScanJob views for getting a partial dataScanJob.
278+
// DataScanJob view options.
273279
enum DataScanJobView {
274280
// The API will default to the `BASIC` view.
275281
DATA_SCAN_JOB_VIEW_UNSPECIFIED = 0;
276282

277-
// Basic view that does not include spec and result.
283+
// Basic view that does not include *spec* and *result*.
278284
BASIC = 1;
279285

280286
// Include everything.
281287
FULL = 10;
282288
}
283289

284290
// Required. The resource name of the DataScanJob:
285-
// projects/{project}/locations/{location_id}/dataScans/{data_scan_id}/dataScanJobs/{data_scan_job_id}
286-
// where `{project}` refers to a project_id or project_number and
291+
// `projects/{project}/locations/{location_id}/dataScans/{data_scan_id}/dataScanJobs/{data_scan_job_id}`
292+
// where `project` refers to a *project_id* or *project_number* and
287293
// `location_id` refers to a GCP region.
288294
string name = 1 [
289295
(google.api.field_behavior) = REQUIRED,
@@ -292,16 +298,15 @@ message GetDataScanJobRequest {
292298
}
293299
];
294300

295-
// Optional. Used to select the subset of DataScan information to return.
296-
// Defaults to `BASIC`.
301+
// Optional. Select the DataScanJob view to return. Defaults to `BASIC`.
297302
DataScanJobView view = 2 [(google.api.field_behavior) = OPTIONAL];
298303
}
299304

300305
// List DataScanJobs request.
301306
message ListDataScanJobsRequest {
302307
// Required. The resource name of the parent environment:
303-
// projects/{project}/locations/{location_id}/dataScans/{data_scan_id}
304-
// where `{project}` refers to a project_id or project_number and
308+
// `projects/{project}/locations/{location_id}/dataScans/{data_scan_id}`
309+
// where `project` refers to a *project_id* or *project_number* and
305310
// `location_id` refers to a GCP region.
306311
string parent = 1 [
307312
(google.api.field_behavior) = REQUIRED,
@@ -325,7 +330,7 @@ message ListDataScanJobsRequest {
325330

326331
// List DataScanJobs response.
327332
message ListDataScanJobsResponse {
328-
// DataScanJobs (metadata only) under a given dataScan.
333+
// DataScanJobs (`BASIC` view only) under a given dataScan.
329334
repeated DataScanJob data_scan_jobs = 1;
330335

331336
// Token to retrieve the next page of results, or empty if there are no more
@@ -352,16 +357,21 @@ message DataScan {
352357
// DataScan execution settings.
353358
message ExecutionSpec {
354359
// Optional. Spec related to how often and when a scan should be triggered.
355-
// If not specified, the default is OnDemand, which means the scan will not
356-
// run until the user calls RunDataScan API.
360+
//
361+
// If not specified, the default is `OnDemand`, which means the scan will
362+
// not run until the user calls `RunDataScan` API.
357363
Trigger trigger = 1 [(google.api.field_behavior) = OPTIONAL];
358364

359-
// If not specified, run a data scan on all data in the table.
360-
// The incremental is immutable, which means once the field is set,
361-
// it cannot be unset, and vice versa.
365+
// Spec related to incremental scan of the data
366+
//
367+
// When an option is selected for incremental scan, it cannot be unset or
368+
// changed. If not specified, a data scan will run for all data in the
369+
// table.
362370
oneof incremental {
363-
// Immutable. The unnested field (Date or Timestamp) that contains values
364-
// that monotonically increase over time.
371+
// Immutable. The unnested field (of type *Date* or *Timestamp*) that
372+
// contains values which monotonically increase over time.
373+
//
374+
// If not specified, a data scan will run for all data in the table.
365375
string field = 100 [(google.api.field_behavior) = IMMUTABLE];
366376
}
367377
}
@@ -376,8 +386,8 @@ message DataScan {
376386
}
377387

378388
// Output only. The relative resource name of the scan, of the form:
379-
// projects/{project}/locations/{location_id}/dataScans/{datascan_id}.
380-
// where `{project}` refers to a project_id or project_number and
389+
// `projects/{project}/locations/{location_id}/dataScans/{datascan_id}`,
390+
// where `project` refers to a *project_id* or *project_number* and
381391
// `location_id` refers to a GCP region.
382392
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
383393

@@ -386,10 +396,12 @@ message DataScan {
386396
string uid = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
387397

388398
// Optional. Description of the scan.
399+
//
389400
// * Must be between 1-1024 characters.
390401
string description = 3 [(google.api.field_behavior) = OPTIONAL];
391402

392403
// Optional. User friendly display name.
404+
//
393405
// * Must be between 1-256 characters.
394406
string display_name = 4 [(google.api.field_behavior) = OPTIONAL];
395407

@@ -411,7 +423,8 @@ message DataScan {
411423
DataSource data = 9 [(google.api.field_behavior) = REQUIRED];
412424

413425
// Optional. DataScan execution settings.
414-
// If not specified, the fields under it will use their default values.
426+
//
427+
// If not specified, the fields in it will use their default values.
415428
ExecutionSpec execution_spec = 10 [(google.api.field_behavior) = OPTIONAL];
416429

417430
// Output only. Status of the data scan execution.
@@ -444,7 +457,7 @@ message DataScan {
444457
}
445458
}
446459

447-
// A DataScanJob represents an instance of a data scan.
460+
// A DataScanJob represents an instance of DataScan execution.
448461
message DataScanJob {
449462
option (google.api.resource) = {
450463
type: "dataplex.googleapis.com/DataScanJob"
@@ -476,8 +489,8 @@ message DataScanJob {
476489
}
477490

478491
// Output only. The relative resource name of the DataScanJob, of the form:
479-
// projects/{project}/locations/{location_id}/dataScans/{datascan_id}/jobs/{job_id}.
480-
// where `{project}` refers to a project_id or project_number and
492+
// `projects/{project}/locations/{location_id}/dataScans/{datascan_id}/jobs/{job_id}`,
493+
// where `project` refers to a *project_id* or *project_number* and
481494
// `location_id` refers to a GCP region.
482495
string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
483496

@@ -526,12 +539,12 @@ message DataScanJob {
526539

527540
// The type of DataScan.
528541
enum DataScanType {
529-
// The DataScan Type is unspecified.
542+
// The DataScan type is unspecified.
530543
DATA_SCAN_TYPE_UNSPECIFIED = 0;
531544

532-
// Data Quality Scan.
545+
// Data Quality scan.
533546
DATA_QUALITY = 1;
534547

535-
// Data Profile Scan.
548+
// Data Profile scan.
536549
DATA_PROFILE = 2;
537550
}

0 commit comments

Comments
 (0)