From 2c30d35bd78a30fa133cd42c362930b7fa2c51e6 Mon Sep 17 00:00:00 2001 From: Evawere Ogbe Date: Wed, 29 May 2019 14:23:10 -0700 Subject: [PATCH] Revert "Synchronize new proto/yaml changes." (#554) This reverts commit 95aa3a2aaa017f8ee3a8911accd94607240ab7a6. --- .circleci/config.yml | 42 ++++ .gitignore | 7 + CONTRIBUTING.md | 28 +++ LICENSE | 201 ++++++++++++++++++ Makefile | 49 +++++ PACKAGES.md | 80 +++++++ README.md | 131 ++++++++++++ google/api/README.md | 5 + google/api/servicecontrol/README.md | 126 +++++++++++ google/api/servicemanagement/README.md | 102 +++++++++ google/appengine/README.md | 12 ++ google/assistant/embedded/README.md | 3 + google/cloud/functions/README.md | 2 + google/cloud/language/README.md | 0 google/cloud/runtimeconfig/README.md | 39 ++++ google/cloud/speech/README.md | 3 + google/container/README.md | 1 + google/datastore/README.md | 1 + google/devtools/cloudbuild/README.md | 1 + google/devtools/clouderrorreporting/README.md | 1 + google/example/library/README.md | 4 + google/firestore/README.md | 0 google/genomics/README.md | 14 ++ google/iam/README.md | 14 ++ google/logging/README.md | 3 + google/longrunning/README.md | 5 + google/privacy/dlp/README.md | 7 + google/pubsub/v1beta2/README.md | 136 ++++++++++++ google/rpc/README.md | 5 + google/streetview/publish/README.md | 1 + google/type/README.md | 16 ++ 31 files changed, 1039 insertions(+) create mode 100644 .circleci/config.yml create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 Makefile create mode 100644 PACKAGES.md create mode 100644 README.md create mode 100644 google/api/README.md create mode 100644 google/api/servicecontrol/README.md create mode 100644 google/api/servicemanagement/README.md create mode 100644 google/appengine/README.md create mode 100644 google/assistant/embedded/README.md create mode 100644 google/cloud/functions/README.md create mode 100644 google/cloud/language/README.md create mode 100644 google/cloud/runtimeconfig/README.md create mode 100644 google/cloud/speech/README.md create mode 100644 google/container/README.md create mode 100644 google/datastore/README.md create mode 100644 google/devtools/cloudbuild/README.md create mode 100644 google/devtools/clouderrorreporting/README.md create mode 100644 google/example/library/README.md create mode 100644 google/firestore/README.md create mode 100644 google/genomics/README.md create mode 100644 google/iam/README.md create mode 100644 google/logging/README.md create mode 100644 google/longrunning/README.md create mode 100644 google/privacy/dlp/README.md create mode 100644 google/pubsub/v1beta2/README.md create mode 100644 google/rpc/README.md create mode 100644 google/streetview/publish/README.md create mode 100644 google/type/README.md diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000000000..2ea704fc334ff --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,42 @@ +--- +version: 2 +jobs: + build: + docker: + - image: googleapis/git + steps: + - checkout + - run: + command: | + if [ "$CIRCLE_BRANCH" == "master" ]; then + git remote add private https://googleapis-publisher:${GITHUB_TOKEN}@github.com/googleapis/googleapis-private.git + git push private HEAD:master + fi + working_directory: /var/code/googleapis/ + smoke-all: + docker: + - image: googleapis/artman:latest + steps: + - checkout + - run: + name: Run smoke tests + command: | + mkdir /tmp/reports + export RUNNING_IN_ARTMAN_DOCKER=True + smoketest_artman.py --root-dir=/var/code/googleapis/ --log=/tmp/reports/smoketest.log + - store_test_results: + path: /tmp/reports + - store_artifacts: + path: /tmp/reports + - store_artifacts: + path: /var/code/googleapis + working_directory: /var/code/googleapis/ + +workflows: + version: 2 + smoketests: + jobs: + - smoke-all: + filters: + branches: + only: master diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000..c4e73d4c15e64 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +OWNERS +README.google +google/internal +google/protobuf +.project +artman-genfiles/ +bazel-* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000..87dfaadd3eefd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,28 @@ +# How to contribute + +We definitely welcome feedback and contribution to Google APIs! Here +is some guideline and information about how to do so. + +## Legal requirements + +In order to protect both you and ourselves, you will need to sign the +[Contributor License Agreement](https://cla.developers.google.com/clas). + +## Technical requirements + +You will need several tools to work with this repository. At minimum, +you need both [Protocol Buffers](https://github.com/google/protobuf) +and [gRPC](https://github.com/grpc) in order to compile this +repository and generate client library source code in various +programming languages. + +To compile the generated code into usable client libraries, you will +need to use appropriate development environments and setup proper +build configurations. + +## Additional note + +Currently, the root's Makefile only lets you generate source code for +the client library in the programming languages supported by +[gRPC](https://github.com/grpc). It does not generate the ready-to-use +client libraries yet. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000000..261eeb9e9f8b2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000000..26801adac71dc --- /dev/null +++ b/Makefile @@ -0,0 +1,49 @@ +# This is a simple Makefile that generates client library source code +# for Google APIs using Protocol Buffers and gRPC for any supported +# language. However, it does not compile the generated code into final +# libraries that can be directly used with application code. +# +# Syntax example: make OUTPUT=./output LANGUAGE=java +# + +# Choose the output directory +OUTPUT ?= ./gens + +# Choose the target language. +LANGUAGE ?= cpp + +# Choose grpc plugin +GRPCPLUGIN ?= /usr/local/bin/grpc_$(LANGUAGE)_plugin + +# Choose the proto include directory. +PROTOINCLUDE ?= /usr/local/include + +# Choose protoc binary +PROTOC ?= protoc + +# Compile the entire repository +# +# NOTE: if "protoc" command is not in the PATH, you need to modify this file. +# + +ifeq ($(LANGUAGE),go) +$(error Go source files are not generated from this repository. See: https://github.com/google/go-genproto) +endif + +FLAGS+= --proto_path=.:$(PROTOINCLUDE) +FLAGS+= --$(LANGUAGE)_out=$(OUTPUT) --grpc_out=$(OUTPUT) +FLAGS+= --plugin=protoc-gen-grpc=$(GRPCPLUGIN) + +SUFFIX:= pb.cc + +DEPS:= $(shell find google $(PROTOINCLUDE)/google/protobuf -type f -name '*.proto' | sed "s/proto$$/$(SUFFIX)/") + +all: $(DEPS) + +%.$(SUFFIX): %.proto + mkdir -p $(OUTPUT) + $(PROTOC) $(FLAGS) $*.proto + +clean: + rm $(patsubst %,$(OUTPUT)/%,$(DEPS)) 2> /dev/null + rm -rd $(OUTPUT) diff --git a/PACKAGES.md b/PACKAGES.md new file mode 100644 index 0000000000000..d67cc31bd63c8 --- /dev/null +++ b/PACKAGES.md @@ -0,0 +1,80 @@ +# Auto-Generated Packages for Google Cloud Platform + +This indexes the gRPC and GAPIC packages delivered to the the [Google Cloud +Platform](https://github.com/GoogleCloudPlatform) teams and where they can be +found. Currently, package delivery is only being done for Python. + +## [Python](https://github.com/GoogleCloudPlatform/gcloud-python) + +### Common +- [GAX core library](https://pypi.python.org/pypi/google-gax) ([source](https://github.com/googleapis/gax-python)) +- [gRPC for common protos](https://pypi.python.org/pypi/googleapis-common-protos) ([source](https://github.com/googleapis/googleapis)) +- [Long-running operations](https://github.com/googleapis/googleapis/blob/master/google/longrunning/operations.proto) + - [GAPIC](https://pypi.python.org/pypi/gapic-google-longrunning) + - gRPC: Part of [gRPC for common protos](https://pypi.python.org/pypi/googleapis-common-protos) + - Documentation: TBD + +### [Cloud Bigtable](https://cloud.google.com/bigtable/) +- GAPIC: TBD +- gRPC: TBD +- Documentation: TBD + +### [Cloud Datastore](https://cloud.google.com/datastore/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-datastore-v1) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-datastore-v1) +- Documentation: TBD + +### [Cloud Identity and Access Management (IAM)](https://cloud.google.com/iam/) +- Admin API + - [GAPIC](https://pypi.python.org/pypi/gapic-google-iam-admin-v1) + - [gRPC](https://pypi.python.org/pypi/grpc-google-iam-admin-v1) + - Documentation: TBD +- Policy Mixin (used by Pub/Sub and others) + - [gRPC](https://pypi.python.org/pypi/grpc-google-iam-v1) + +### [Cloud Natural Language](https://cloud.google.com/natural-language/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-language-v1beta1) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-language-v1beta1) +- Documentation: TBD + +### [Cloud Pub/Sub](https://cloud.google.com/pubsub/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-pubsub-v1) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-pubsub-v1) +- [Documentation](http://pythonhosted.org/gax-google-pubsub-v1/): + For old `gax` namespace... will be updated soon for `gapic` namespace. + +### [Cloud Speech](https://cloud.google.com/speech/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-speech-v1beta1) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-speech-v1beta1) +- Documentation: TBD + +### [Cloud Vision](https://cloud.google.com/vision/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-vision-v1) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-vision-v1) +- [Documentation](http://pythonhosted.org/gax-google-cloud-vision-v1/): + For old `gax` namespace... will be updated soon for `gapic` namespace. + +### [Stackdriver Debugger](https://cloud.google.com/debugger/) +- GAPIC: TBD +- gRPC: TBD +- Documentation: TBD + +### [Stackdriver Error Reporting](https://cloud.google.com/error-reporting/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-error-reporting-v1beta1) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-error-reporting-v1beta1) +- Documentation: TBD + +### [Stackdriver Logging](https://cloud.google.com/logging/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-cloud-logging-v2) +- [gRPC](https://pypi.python.org/pypi/grpc-google-cloud-logging-v2) +- [Documentation](http://gapic-google-cloud-logging-v2.readthedocs.io) + +### [Stackdriver Monitoring](https://cloud.google.com/monitoring/) +- [GAPIC](https://pypi.python.org/pypi/gapic-google-monitoring-v3) +- [gRPC](https://pypi.python.org/pypi/grpc-google-monitoring-v3) +- Documentation: TBD + +### [Stackdriver Trace](https://cloud.google.com/trace/) +- GAPIC: TBD +- gRPC: TBD +- Documentation: TBD diff --git a/README.md b/README.md new file mode 100644 index 0000000000000..3e5a4cdd7e669 --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +# Google APIs + +This repository contains the original interface definitions of public +Google APIs that support both REST and gRPC protocols. Reading the +original interface definitions can provide a better understanding of +Google APIs and help you to utilize them more efficiently. You can also +use these definitions with open source tools to generate client +libraries, documentation, and other artifacts. + +## Building +### Bazel + +The recommended way to build the API client libraries is through +[Bazel](https://bazel.build/) >= 0.23.0. + +First, [install bazel](https://docs.bazel.build/versions/master/install.html). + +To build all libraries: + +``` +bazel build //... +``` + +To test all libraries: + +``` +bazel test //... +``` + +To build one library in all languages: + +``` +bazel build //google/example/library/v1/... +``` + +To build the Java package for one library: + +``` +bazel build //google/example/library/v1:google-cloud-library-v1-java +``` + +Bazel packages exist in all the libraries for Java and Go. + +### Artman + +API client libraries can be built directly from files in this repo using +[Artman](https://github.com/googleapis/artman). The latest generation status can +be tracked [here](https://circleci.com/gh/googleapis/googleapis) which currently +has status [![CircleCI](https://circleci.com/gh/googleapis/googleapis.svg?style=svg)](https://circleci.com/gh/googleapis/googleapis). + +To build the Java package for one library: + +``` +artman --config google/example/library/artman_library_example_v1.yaml generate java_gapic +``` + +Artman can only build one library in one language at a time. + +For more details on all Google APIs and developer tools, see the [Google +Developers](https://developers.google.com/products/) site. + +## Overview + +Google APIs are typically deployed as API services that are hosted +under different DNS names. One API service may implement multiple APIs +and multiple versions of the same API. + +Google APIs use [Protocol Buffers](https://github.com/google/protobuf) +version 3 (proto3) as their Interface Definition Language (IDL) to +define the API interface and the structure of the payload messages. The +same interface definition is used for both REST and RPC versions of the +API, which can be accessed over different wire protocols. + +There are several ways of accessing Google APIs: + +1. JSON over HTTP: You can access all Google APIs directly using JSON +over HTTP, using +[Google API client library](https://developers.google.com/api-client-library) +or third-party API client libraries. + +2. Protocol Buffers over gRPC: You can access Google APIs published +in this repository through [GRPC](https://github.com/grpc), which is +a high-performance binary RPC protocol over HTTP/2. It offers many +useful features, including request/response multiplex and full-duplex +streaming. + +3. [Google Cloud Client Libraries](https://cloud.google.com/apis/docs/cloud-client-libraries): +You can use these libraries to access Google Cloud APIs. They are based +on gRPC for better performance and provide idiomatic client surface for +better developer experience. + +## Discussions + +This repo contains copies of Google API definitions and related files. For +discussions or to raise issues about +[Google API client libraries](https://github.com/googleapis), +[GRPC](https://github.com/grpc) or +[Google Cloud Client Libraries](https://github.com/googlecloudplatform) please +refer to the repos associated with each area. + +## Repository Structure + +This repository uses a directory hierarchy that reflects the Google +API product structure. In general, every API has its own root +directory, and each major version of the API has its own subdirectory. +The proto package names exactly match the directory: this makes it +easy to locate the proto definitions and ensures that the generated +client libraries have idiomatic namespaces in most programming +languages. Alongside the API directories live the configuration files +for the [GAPIC toolkit](https://github.com/googleapis/toolkit). + +**NOTE:** The major version of an API is used to indicate breaking +change to the API. + +## Generate gRPC Source Code + +To generate gRPC source code for Google APIs in this repository, you +first need to install both Protocol Buffers and gRPC on your local +machine, then you can run `make LANGUAGE=xxx all` to generate the +source code. You need to integrated the generated source code into +your application build system. + +**NOTE:** The Makefile is only intended to generate source code for the +entire repository. It is not for generating linkable client library +for a specific API. Please see other repositories under +https://github.com/googleapis for generating linkable client libraries. + +### Go gRPC Source Code +It is difficult to generate Go gRPC source code from this repository, +since Go has different directory structure. +Please use [this repository](https://github.com/google/go-genproto) instead. diff --git a/google/api/README.md b/google/api/README.md new file mode 100644 index 0000000000000..eafe588022375 --- /dev/null +++ b/google/api/README.md @@ -0,0 +1,5 @@ +This folder contains the schema of the configuration model for the API services +platform. + +**Note**: Protos under this directory are in Alpha status, and therefore are +subject to breaking changes. diff --git a/google/api/servicecontrol/README.md b/google/api/servicecontrol/README.md new file mode 100644 index 0000000000000..3d9590ee029cc --- /dev/null +++ b/google/api/servicecontrol/README.md @@ -0,0 +1,126 @@ +Google Service Control provides control plane functionality to managed services, +such as logging, monitoring, and status checks. This page provides an overview +of what it does and how it works. + +## Why use Service Control? + +When you develop a cloud service, you typically start with the business +requirements and the architecture design, then proceed with API definition +and implementation. Before you put your service into production, you +need to deal with many control plane issues: + +* How to control access to your service. +* How to send logging and monitoring data to both consumers and producers. +* How to create and manage dashboards to visualize this data. +* How to automatically scale the control plane components with your service. + +Service Control is a mature and feature-rich control plane provider +that addresses these needs with high efficiency, high scalability, +and high availability. It provides a simple public API that can be accessed +from anywhere using JSON REST and gRPC clients, so when you move your service +from on-premise to a cloud provider, or from one cloud provider to another, +you don't need to change the control plane provider. + +Services built using Google Cloud Endpoints already take advantage of +Service Control. Cloud Endpoints sends logging and monitoring data +through Google Service Control for every request arriving at its +proxy. If you need to report any additional logging and monitoring data for +your Cloud Endpoints service, you can call the Service Control API directly +from your service. + +The Service Control API definition is open sourced and available on +[GitHub](https://github.com/googleapis/googleapis/tree/master/google/api/servicecontrol). +By changing the DNS name, you can easily use alternative implementations of +the Service Control API. + +## Architecture + +Google Service Control works with a set of *managed services* and their +*operations* (activities), *checks* whether an operation is allowed to proceed, +and *reports* completed operations. Behind the scenes, it leverages other +Google Cloud services, such as +[Google Service Management](/service-management), +[Stackdriver Logging](/logging), and [Stackdriver Monitoring](/monitoring), +while hiding their complexity from service producers. It enables service +producers to send telemetry data to their consumers. It uses caching, +batching, aggregation, and retries to deliver higher performance and +availability than the individual backend systems it encapsulates. + +
+
+ The overall architecture of a service that uses Google Service Control. +
+
Figure 1: Using Google Service Control.
+
+ +The Service Control API provides two methods: + +* [`services.check`](/service-control/reference/rest/v1/services/check), used for: + * Ensuring valid consumer status + * Validating API keys +* [`services.report`](/service-control/reference/rest/v1/services/report), used for: + * Sending logs to Stackdriver Logging + * Sending metrics to Stackdriver Monitoring + +We’ll look at these in more detail in the rest of this overview. + +## Managed services + +A [managed service](/service-management/reference/rest/v1/services) is +a network service managed by +[Google Service Management](/service-management). Each managed service has a +unique name, such as `example.googleapis.com`, which must be a valid +fully-qualified DNS name, as per RFC 1035. + +For example: + +* Google Cloud Pub/Sub (`pubsub.googleapis.com`) +* Google Cloud Vision (`vision.googleapis.com`) +* Google Cloud Bigtable (`bigtable.googleapis.com`) +* Google Cloud Datastore (`datastore.googleapis.com`) + +Google Service Management manages the lifecycle of each service’s +configuration, which is used to customize Google Service Control's behavior. +Service configurations are also used by Google Cloud Console +for displaying APIs and their settings, enabling/disabling APIs, and more. + +## Operations + +Google Service Control uses the generic concept of an *operation* +to represent the +activities of a managed service, such as API calls and resource usage. Each +operation is associated with a managed service and a specific service +consumer, and has a set of properties that describe the operation, such as +the API method name and resource usage amount. For more information, see the +[Operation definition](/service-control/rest/v1/Operation). + +## Check + +The [`services.check`](/service-control/reference/rest/v1/services/check) +method determines whether an operation should be allowed to proceed +for a managed service. + +For example: + +* Check if the consumer is still active. +* Check if the consumer has enabled the service. +* Check if the API key is still valid. + +By performing multiple checks within a single method call, it provides +better performance, higher reliability, and reduced development cost to +service producers compared to checking with multiple backend systems. + +## Report + +The [`services.report`](/service-control/reference/rest/v1/services/report) +method reports completed operations for +a managed service to backend systems, such as logging and monitoring. The +reported data can be seen in Google API Console and Google Cloud Console, +and retrieved with appropriate APIs, such as the Stackdriver Logging and +Stackdriver Monitoring APIs. + +## Next steps + +* Read our [Getting Started guide](/service-control/getting-started) to find out + how to set up and use the Google Service Control API. diff --git a/google/api/servicemanagement/README.md b/google/api/servicemanagement/README.md new file mode 100644 index 0000000000000..e3e36df498da2 --- /dev/null +++ b/google/api/servicemanagement/README.md @@ -0,0 +1,102 @@ +Google Service Management manages a set of *services*. Service +Management allows *service producers* to +publish their services on Google Cloud Platform so that they can be discovered +and used by *service consumers*. It also handles the tasks of tracking +service lifecycle and programming various backend systems -- such as +[Stackdriver Logging](https://cloud.google.com/stackdriver), +[Stackdriver Monitoring](https://cloud.google.com/stackdriver) -- to support +the managed services. + +If you are a service producer, you can use the Google Service Management API +and [Google Cloud SDK (gcloud)](/sdk) to publish and manage your services. +Each managed service has a service configuration which declares various aspects +of the service such as its API surface, along with parameters to configure the +supporting backend +systems, such as logging and monitoring. If you build your service using +[Google Cloud Endpoints](https://cloud.google.com/endpoints/), the service +configuration will be handled automatically. + +If you are a service consumer and want to use a managed service, you can use the +Google Service Management API or [Google Cloud Console](https://console.cloud.google.com) +to activate the +service for your [Google developer project](https://developers.google.com/console/help/new/), +then start using its APIs and functions. + +## Managed services + +REST URL: `https://servicemanagement.googleapis.com/v1/services/{service-name}`
+REST schema is defined [here](/service-management/reference/rest/v1/services). + +A managed service refers to a network service managed by +Service Management. Each managed service has a unique name, such as +`example.googleapis.com`, which must be a valid fully-qualified DNS name, as per +RFC 1035. + +A managed service typically provides some REST APIs and/or other +functions to their service consumers, such as mobile apps or cloud services. + +Service producers can use methods, such as +[services.create](/service-management/reference/rest/v1/services/create), +[services.delete](/service-management/reference/rest/v1/services/delete), +[services.undelete](/service-management/reference/rest/v1/services/undelete), +to manipulate their managed services. + +## Service producers + +A service producer is the Google developer project responsible for publishing +and maintaining a managed service. Each managed service is owned by exactly one +service producer. + +## Service consumers + +A service consumer is a Google developer project that has enabled and can +invoke APIs on a managed service. A managed service can have many service +consumers. + +## Service configuration + +REST URL: `https://servicemanagement.googleapis.com/v1/services/{service-name}/configs/{config_id}`
+REST schema is defined [here](/service-management/reference/rest/v1/services.configs). + +Each managed service is described by a service configuration which covers a wide +range of features, including its name, title, RPC API definitions, +REST API definitions, documentation, authentication, and more. + +To change the configuration of a managed service, the service producer needs to +publish an updated service configuration to Service Management. +Service Management keeps a history of published +service configurations, making it possible to easily retrace how a service's +configuration evolved over time. Service configurations can be published using +the +[services.configs.create](/service-management/reference/rest/v1/services.configs/create) +or [services.configs.submit](/service-management/reference/rest/v1/services.configs/submit) +methods. + +Alternatively, `services.configs.submit` allows publishing an +[OpenAPI](https://github.com/OAI/OpenAPI-Specification) specification, formerly +known as the Swagger Specification, which is automatically converted to a +corresponding service configuration. + +## Service rollout + +REST URL: `https://servicemanagement.googleapis.com/v1/services/{service-name}/rollouts/{rollout-id}`
+REST schema is defined [here](/service-management/reference/rest/v1/services.rollouts). + +A `Rollout` defines how Google Service Management should deploy service +configurations to backend systems and how the configurations take effect at +runtime. It lets service producers specify multiple service configuration +versions to be deployed together, and a strategy that indicates how they +should be used. + +Updating a managed service's configuration can be dangerous, as a configuration +error can lead to a service outage. To mitigate risks, Service Management +supports gradual rollout of service configuration changes. This feature gives +service producers time to identity potential issues and rollback service +configuration changes in case of errors, thus minimizing the customer +impact of bad configurations. For example, you could specify that 5% of traffic +uses configuration 1, while the remaining 95% uses configuration 2. + +Service Management keeps a history of rollouts so that service +producers can undo to previous configuration versions. You can rollback a configuration +by initiating a new `Rollout` that clones a previously submitted +rollout record. \ No newline at end of file diff --git a/google/appengine/README.md b/google/appengine/README.md new file mode 100644 index 0000000000000..54e45e6f8d65f --- /dev/null +++ b/google/appengine/README.md @@ -0,0 +1,12 @@ +# Google App Engine Admin API + +## Overview + +The Google App Engine Admin API is a RESTful API for managing App Engine +applications. The Admin API provides programmatic access to several of the App +Engine administrative operations that are found in the +[Google Cloud Platform Console](https://cloud.google.com/appengine/docs/developers-console). + +## Documentation + +[Google App Engine Admin API Documentation](https://cloud.google.com/appengine/docs/admin-api/) \ No newline at end of file diff --git a/google/assistant/embedded/README.md b/google/assistant/embedded/README.md new file mode 100644 index 0000000000000..756d9ff3ec43f --- /dev/null +++ b/google/assistant/embedded/README.md @@ -0,0 +1,3 @@ +The `Google Assistant API` allows developers to embed the Google Assistant into +their devices. It provides an audio-in (spoken user query) and +audio-out (Assistant spoken response). diff --git a/google/cloud/functions/README.md b/google/cloud/functions/README.md new file mode 100644 index 0000000000000..4a9d225c7b68f --- /dev/null +++ b/google/cloud/functions/README.md @@ -0,0 +1,2 @@ +API for managing lightweight user-provided functions executed in response to +events. \ No newline at end of file diff --git a/google/cloud/language/README.md b/google/cloud/language/README.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/google/cloud/runtimeconfig/README.md b/google/cloud/runtimeconfig/README.md new file mode 100644 index 0000000000000..49c1d8717fffc --- /dev/null +++ b/google/cloud/runtimeconfig/README.md @@ -0,0 +1,39 @@ +[TOC] + +# Introduction + +The RuntimeConfig service provides Google Cloud Platform users the ability to +dynamically configure your service. + +The RuntimConfig service creates and manages RuntimeConfig resources +within a Google Cloud Project and various variables within said resource. + +## Details + +Each cloud project can create multiple **Config** objects. A **Config** object +by itself does not contain any configuration information, but rather is a +logical grouping of variables. Variable names are hierarchical and follow file +system style, where only leaf nodes can contain values. + +For example, you can have a configuration called *Flags*. Within that +configuration object, you can create the following variables. + +* `/ports/service_port` +* `/ports/monitoring_port` +* `/ports/admin_port` + +This creates three variables: `/ports/serve_port`, `/ports/monitoring_port`, +`/ports/admin_port`. Note that `/ports` cannot have a value but it can be +listed. + +### Setup + +In order to make requests to RuntimeConfig service, you need to enable the API +for your project. + +To achieve that, go to the +[Google Cloud Console](https://console.cloud.google.com/apis/api/runtimeconfig.googleapis.com/overview) +and enable *Google Cloud RuntimeConfig API* for your project. + +The documentation for this service is located +[here](https://cloud.google.com/deployment-manager/runtime-configurator/reference/rest/). diff --git a/google/cloud/speech/README.md b/google/cloud/speech/README.md new file mode 100644 index 0000000000000..c45f0f21a16a9 --- /dev/null +++ b/google/cloud/speech/README.md @@ -0,0 +1,3 @@ +# Introduction + +Google Cloud Speech API provides speech recognition as a service. diff --git a/google/container/README.md b/google/container/README.md new file mode 100644 index 0000000000000..8b137891791fe --- /dev/null +++ b/google/container/README.md @@ -0,0 +1 @@ + diff --git a/google/datastore/README.md b/google/datastore/README.md new file mode 100644 index 0000000000000..8b137891791fe --- /dev/null +++ b/google/datastore/README.md @@ -0,0 +1 @@ + diff --git a/google/devtools/cloudbuild/README.md b/google/devtools/cloudbuild/README.md new file mode 100644 index 0000000000000..12ffda1a20444 --- /dev/null +++ b/google/devtools/cloudbuild/README.md @@ -0,0 +1 @@ +The Google Cloud Container Builder API lets you to build an application or part of an application from source code stored in Google Cloud Storage or a Google Cloud Source Repository and package it into container images. The container images are then stored in Google Container Registry. You can optionally copy the images to another container registry as required. diff --git a/google/devtools/clouderrorreporting/README.md b/google/devtools/clouderrorreporting/README.md new file mode 100644 index 0000000000000..3edcebe6f26a0 --- /dev/null +++ b/google/devtools/clouderrorreporting/README.md @@ -0,0 +1 @@ +Read more about the Stackdriver Error Reporting API [here](https://cloud.google.com/error-reporting/reference/) diff --git a/google/example/library/README.md b/google/example/library/README.md new file mode 100644 index 0000000000000..ee3aa684d58ba --- /dev/null +++ b/google/example/library/README.md @@ -0,0 +1,4 @@ +# Introduction +This is a Google example service representing a simple digital library. +It manages a collection of shelf resources, and each shelf owns a collection +of book resources. diff --git a/google/firestore/README.md b/google/firestore/README.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/google/genomics/README.md b/google/genomics/README.md new file mode 100644 index 0000000000000..8bc621804acf8 --- /dev/null +++ b/google/genomics/README.md @@ -0,0 +1,14 @@ +Stores, processes, explores and shares genomic data. This API implements +the Global Alliance for Genomics and Health (GA4GH) v0.5.1 API as well as +several extensions. + +The Google Genomics API supports access via both +[JSON/REST](https://cloud.google.com/genomics/reference/rest) and +[gRPC](https://cloud.google.com/genomics/reference/rpc). JSON/REST is more +broadly available and is easier for getting started with Google Genomics; it +works well for small metadata resources (datasets, variant sets, read group +sets) and for browsing small genomic regions for datasets of any size. For +performant bulk data access (reads and variants), use gRPC. + +See also an [overview of genomic resources](https://cloud.google.com/genomics/v1/users-guide) +and an overview of [Genomics on Google Cloud](https://cloud.google.com/genomics/overview). \ No newline at end of file diff --git a/google/iam/README.md b/google/iam/README.md new file mode 100644 index 0000000000000..c402a9dd05b55 --- /dev/null +++ b/google/iam/README.md @@ -0,0 +1,14 @@ +# Introduction + +# Key Concepts + +## Service Account + +A Service Account is an account used to identify services (non-humans) to Google. +A Service Account has a list of Service Account Keys, which can be used to authenticate to Google. + +## Service Account Keys + +A Service Account Key is a public/private keypair generated by Google. Google retains the public +key, while the customer is given the private key. The private key can be used to [sign JWTs and +authenticate Service Accounts to Google](https://developers.google.com/identity/protocols/OAuth2ServiceAccount#authorizingrequests). diff --git a/google/logging/README.md b/google/logging/README.md new file mode 100644 index 0000000000000..2f14ba1b9d1da --- /dev/null +++ b/google/logging/README.md @@ -0,0 +1,3 @@ +# Introduction + +The Stackdriver Logging service. diff --git a/google/longrunning/README.md b/google/longrunning/README.md new file mode 100644 index 0000000000000..905642277f562 --- /dev/null +++ b/google/longrunning/README.md @@ -0,0 +1,5 @@ +# Google Long Running Operations API + +This package contains the definition of an abstract interface that +manages long running operations with API services. See +[google.longrunning.Operations][] for details. \ No newline at end of file diff --git a/google/privacy/dlp/README.md b/google/privacy/dlp/README.md new file mode 100644 index 0000000000000..629d72b89d547 --- /dev/null +++ b/google/privacy/dlp/README.md @@ -0,0 +1,7 @@ +# Google Data Loss Prevention (DLP) API + +The Google Data Loss Prevention API provides methods for detection +of privacy-sensitive fragments in text, images, and Google Cloud +Platform storage repositories. + +Documentation: https://cloud.google.com/dlp/docs diff --git a/google/pubsub/v1beta2/README.md b/google/pubsub/v1beta2/README.md new file mode 100644 index 0000000000000..bc2f60378b144 --- /dev/null +++ b/google/pubsub/v1beta2/README.md @@ -0,0 +1,136 @@ +## Overview +This file describes an API for a Pub/Sub (Publish/Subscribe) system. This system +provides a reliable many-to-many communication mechanism between independently +written publishers and subscribers where the publisher publishes messages to +*topics* and each subscriber creates a *subscription* and consumes *messages* +from it. + +1. The Pub/Sub system maintains bindings between topics and subscriptions. +2. A publisher publishes messages into a topic. +3. The Pub/Sub system delivers messages from topics into attached + subscriptions. +4. A subscriber receives pending messages from its subscription and + acknowledges each one to the Pub/Sub system. +5. The Pub/Sub system removes acknowledged messages from that subscription. + +## Data Model +The data model consists of the following: + +* **Topic**: A topic is a resource to which messages are published by + publishers. Topics are named, and the name of the topic is unique within the + Pub/Sub system. + +* **Subscription**: A subscription records the subscriber's interest in a + topic. The Pub/Sub system maintains those messages which still need + to be delivered and acknowledged so that they can retried as needed. + The set of messages that have not been acknowledged is called the + subscription backlog. + +* **Message**: A message is a unit of data that flows in the system. It + contains opaque data from the publisher along with its *attributes*. + +* **Message Attributes** (optional): A set of opaque key-value pairs assigned + by the publisher to a message. Attributes are delivered unmodified to + subscribers together with the message data, if there's any. + +## Publisher Flow +A publisher publishes messages to the topic using the `Publish` call: + +```data +PubsubMessage message; +message.set_data("...."); +message.attributes.put("key1", "value1"); +PublishRequest request; +request.set_topic("topicName"); +request.add_message(message); +Publisher.Publish(request); +``` + +## Subscriber Flow +The subscriber part of the API is richer than the publisher part and has a +number of concepts for subscription creation and use: + +1. A subscriber (user or process) creates a subscription using the + `CreateSubscription` call. + +2. A subscriber receives messages in one of two ways: via pull or push. + + * To receive messages via pull, a subscriber calls the `Pull` method on the + `Subscriber` to get messages from the subscription. For each individual + message, the subscriber may use the `ack_id` received in the + `PullResponse` to `Acknowledge` the message, or modify the *ack deadline* + with `ModifyAckDeadline`. See the `Subscription.ack_deadline_seconds` + field documentation for details on the ack deadline behavior. Messages + must be acknowledged or they will be redelivered in a future `Pull` call. + + **Note:** Messages may be consumed in parallel by multiple processes + making `Pull` calls to the same subscription; this will result in the set + of messages from the subscription being split among the processes, each + process receiving a subset of the messages. + + * To receive messages via push, the `PushConfig` field must be specified in + the `Subscription` parameter when creating a subscription, or set with + `ModifyPushConfig`. The PushConfig specifies an endpoint at which the + subscriber exposes the `PushEndpointService` or some other handler, + depending on the endpoint. Messages are received via the + `ProcessPushMessage` method. The push subscriber responds to the method + with a result code that indicates one of three things: `Acknowledge` (the + message has been successfully processed and the Pub/Sub system may delete + it), `Nack` (the message has been rejected and the Pub/Sub system should + resend it at a later time). + + **Note:** The endpoint may be a load balancer for better scalability, so + that multiple processes may handle the message processing load. + +Subscription creation: + +```data +Subscription subscription; +subscription.set_topic("topicName"); +subscription.set_name("subscriptionName"); +subscription.push_config().set_push_endpoint("machinename:8888"); +Subscriber.CreateSubscription(subscription); +``` + +Consuming messages via pull: + +```data +// The subscription must be created without setting the push_config field. + +PullRequest pull_request; +pull_request.set_subscription("subscriptionName"); +pull_request.set_return_immediately(false); +pull_request.set_max_messages(10); +while (true) { + PullResponse pull_response; + AcknowledgeRequest ack_request; + ackRequest.set_subscription("subscriptionName"); + if (Subscriber.Pull(pull_request, pull_response) == OK) { + for (ReceivedMessage received in pull_response.received_messages()) { + Process(received.message().data()); + ackRequest.add_ack_id(received.ack_id()); + } + } + if (ackRequest.ack_ids().size() > 0) { + Subscriber.Acknowledge(ack_request); + } +} +``` + +## Reliability Semantics +When a subscriber successfully creates a subscription using +`Subscriber.CreateSubscription`, it establishes a "subscription point" for +that subscription, no later than the time that `Subscriber.CreateSubscription` +returns. The subscriber is guaranteed to receive any message published after +this subscription point. Note that messages published before the subscription +point may or may not be delivered. + +Messages are not delivered in any particular order by the Pub/Sub system. +Furthermore, the system guarantees *at-least-once* delivery of each message +until acknowledged. + +## Deletion +Both topics and subscriptions may be deleted. + +When a subscription is deleted, all messages are immediately dropped. If it +is a pull subscriber, future pull requests will return NOT_FOUND. diff --git a/google/rpc/README.md b/google/rpc/README.md new file mode 100644 index 0000000000000..509881429df1e --- /dev/null +++ b/google/rpc/README.md @@ -0,0 +1,5 @@ +# Google RPC + +This package contains type definitions for general RPC systems. While +[gRPC](https://github.com/grpc) is using these defintions, they +are not designed specifically to support gRPC. diff --git a/google/streetview/publish/README.md b/google/streetview/publish/README.md new file mode 100644 index 0000000000000..d8f3534bdfc5a --- /dev/null +++ b/google/streetview/publish/README.md @@ -0,0 +1 @@ +An API to contribute 360 photos to Google Street View. The API also allows the users to connect photos, update metadata of the photos, generate photo collections, and delete photos. \ No newline at end of file diff --git a/google/type/README.md b/google/type/README.md new file mode 100644 index 0000000000000..6caf02cf1f5eb --- /dev/null +++ b/google/type/README.md @@ -0,0 +1,16 @@ +# Google Common Types + +This package contains definitions of common types for Google APIs. +All types defined in this package are suitable for different APIs to +exchange data, and will never break binary compatibility. They should +have design quality comparable to major programming languages like +Java and C#. + +NOTE: Some common types are defined in the package `google.protobuf` +as they are directly supported by Protocol Buffers compiler and +runtime. Those types are called Well-Known Types. + +## Java Utilities + +A set of Java utilities for the Common Types are provided in the +`//java/com/google/type/util/` package. \ No newline at end of file